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CHAPTER  ONE 


A Map  of  TOS 


The  disk  drlve(s),  screen,  kQ^ard,  circuitry,  and  other  components 
of  a computer  do  nothing  without  Instructions.  The  software  Instruc- 
tions that  permit  the  different  hardware  parts  of  a computer  to 
Interact  are  known  as  operating  ^tems.  Operating  ^tems  control 
the  hardware  functions  that  a computer  must  perform:  system  tim- 
ing, program  Initiation,  command  Interpretation,  video  display, 
keyboard  Interpretation,  communication  with  external  devices  (such 
as  printers,  disk  drives,  and  modems),  and  memoiy  management 

Designing  an  operating  ^tem  that  works  is  not  a trivial  task 
because  of  the  complexity  of  the  functions  involved.  To  facilitate  this 
task,  an  operating  intern  Is  usually  broken  into  modules.  Most 
operating  ^tems  are  configured  in  modules  that  generally  include  a 
Disk  Operating  System  (DOS),  a Basic  Input/Output  System  (BIOS), 
and  some  extended  functions  for  providing  ea^  access  to  the  special 
hardware  features  built  Into  the  computer.  DOS  usua%  handles 
routines  for  manipulating  data  on  disks,  i.e.,  reading,  writing,  delet- 
ing, and  organizing  files.  BIOS  provides  routines  for  primary  com- 
munication with  the  keyboard,  screen,  and  other  external  devices.  The 
extended  functions  can  include  graphics,  sound,  and  memory  manage- 
ment 

The  operating  system  for  the  Atari  ST  computer  is  called  TOS.  Like 
most  other  operating  ^tems,  TOS  is  modularly  designed  and  con- 
sists of  several  components.  This  chs^ter  explains  what  is  Included 
in  TOS,  the  function  of  each  component  of  the  operating  system,  and 
the  relationships  between  the  components.  TOS  includes  all  of  the 
basic  parts,  or  modules,  of  an  operating  system  listed  above.  However, 
it  organizes  them  into  three  basic  components:  GEM,  XBIOS,  and  the 
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Line  A handler.  Each  of  these  components  governs  different  functions 
of  the  system,  but  in  some  cases  there  is  an  overlap  in  function.  The 
component  with  the  most  obvious  difference  is  the  Graphics  Environ- 
ment Manager  (GEM);  therefore,  it  is  the  first  module  examined. 


GEM 


Introduction 

A graphics  enviroiunent  is  exactfy  virhat  it  sounds  like:  one  that  uses 
pictures  rather  than  text  to  represent  specific  tasks  the  computer  can 
perform.  Ebcamples  indude  a filing  cabinet  representing  the  floppy 
disk  drives  that  store  files  and  a trash  can  representing  the  place  to 
put  data  no  longer  needed.  In  general,  an  environment  manager  keeps 
track  of  virhat  is  shown  on  the  screen.  A graphics  environment  man- 
ager. therefore,  keeps  in  order  the  special  features  the  gr^hlcs  envi- 
ronment uses:  icons,  windows,  and  other  functions. 

Using  a picture  language  for  communication  dates  back  to  the 
ancient  Egyptians,  but  its  use  in  the  dectronlc  communications 
world  is  a far  more  recent  development  In  fact  most  computers  still 
use  a text-based  system  where  the  user  must  type  commands  on  the 
keyboard  rather  than  pointing  with  a mouse.  Obviousty,  a graphics- 
based  computer  program  is  much  easier  for  a beginning  computer 
user  to  Interact  with. 

If  it  is  such  a user-friendly  way  of  doing  business  with  a computer, 
why  don’t  all  computers  utilize  a grs^hics  environment?  It’s  a matter 
of  convenience  and  economics.  The  hardware  and  software  required 
to  run  a text  environment  cost  much  less  and  are  much  simpler  to 
develop  than  that  needed  for  a graphics  environment  The  cost  savings 
occur  primarity  in  the  software  end  of  things  because  of  the  time  in- 
volved in  development  Writing  a program  for  a text  environment 
merely  requires  sending  text  to  a display  and  reading  text  fijom  a key- 
board, which  is  a relatlvety  simple  interfiice.  A graphics  environment 
on  the  other  hand,  must  be  able  to  accept  text  and  manipulate  many 
complex  Images.  It  has  to  handle  menus,  windows,  mouse  movement 
and  input— clicks  and  drags,  icons,  and  other  images.  Each  of  these 
also  contains  several  complex  structures,  such  as  a size  box  and  title 
bar  for  a window,  which  must  also  be  addressed  ty  the  environment 
manager. 

The  Xerox  Palo  Alto  Research  Center  (PARC)  first  developed  a 
graphics  environment  using  a mouse,  menus,  windows,  and  icons. 
Unfortunately,  at  that  time,  the  hardware  allowing  graphics  displays 
was  still  quite  expensive:  this  prevented  the  graphics  environment 
fiom  being  pursued  commerclalty. 
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^ple  Computer  designed  the  Lisa  and  then  the  Macintosh  to  use 
a graphics-based  interface— one  with  the  ability  to  store  the  various 
components  of  the  graphics  environment  in  libraries  for  ea^  access 
by  outside  programs.  This  heralded  a new  beginning  for  user-com- 
puter communications. 

The  best  design  aspect  of  the  Macintosh  was  that  its  environment 
routines  were  built  into  the  computer.  This  allowed  programmers  to 
access  the  routines  from  their  programs  rather  than  having  to  write 
thousands  of  lines  of  code  to  handle  windows,  menus,  the  mouse,  and 
so  on. 

GEM  and  the  Macintosh  environments  are  similar  in  that  they  both 
provide  graphics  environments  in  which  to  program.  However.  GEM 
goes  beyond  the  Macintosh  environment  in  an  important  aspect- 
GEM  is  a portable  environment 

Digital  Research  designed  GEM  for  implementation  on  many  dif- 
ferent types  of  computers,  for  example,  the  Atari  ST,  IBM  PC,  and  IBM 
PC  compatibles.  This  means  that  a program  written  for  one  computer 
using  GEM  can  be  moved  to  a different  computer  without  changing 
the  logic  of  the  program.  If  the  program  were  Inltlalfy  written  in  a 
portable  language  such  as  C.  virtual^  no  changes  would  be  needed. 
You  could  simply  transfer  the  source  code  to  the  desired  computer 
^tem  and  then  recompile  the  program. 

GEM  not  only  affords  portability  among  different  computers  but 
also  provides  hardware  independence  for  output  Basically,  a com- 
puter commimicates  to  the  user  by  providing  feedback  through  some 
output  device,  usually  a video  screen  or  printer.  E^ach  output  device 
has  different  characteristics  for  its  display,  including  line  width,  dot 
size,  and  graphics  capabilities.  To  translate  a display  from  the  screen 
onto  paper,  the  data  in  the  display  must  be  reformatted  to  accom- 
modate the  differing  characteristics  of  the  paper  device.  M^thout  GEM 
a prograunmer  would  need  to  write  an  output  routine  for  each  device 
to  account  for  these  differences.  However,  GEM  supplies  generic 
routines  that  take  care  of  this  translation.  These  routines  utilize 
pieces  of  softwatre  called  device  drivers. 

E^ch  device  driver  contains  a description  of  the  device’s  specific 
chauacterlstlcs.  When  a programmer  runs  a program  written  using 
GEM,  the  GEM  routines  access  the  appropriate  device  drivers.  These 
convert  the  generic  GEM  routine  information  into  device-specific 
output  This  meams  that  you  can  write  a sin^e  function  to  draw  a 
series  of  circles  using  GEM  routines.  That  function  can  then  be  used 
to  display  the  circles  on  a screen,  a graphics  printer,  or  a plotter 
without  changes  to  the  program.  The  usefulness  of  device  indepen- 
dence should  be  falrty  obvious.  This  function  of  the  ST  is  exaunined 
further  in  this  chapter  when  the  GEM  VDI  is  discussed. 

The  GEM  interface  has  a two-fold  function.  First  GEM  is  an  inter- 
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face  between  the  user  and  the  computer.  It  can  make  computer 
operations  much  easier,  particulaify  for  a novice,  by  providing  win- 
dows, menus,  and  simple  icons  in  place  of  text  Second,  GEM  is  an 
interface  between  the  programmer  and  the  available  hardware.  With 
GEM,  the  time  it  takes  to  write  user  interfaces  for  the  variety  of  hard- 
ware current^  available  greatly  decreases,  and  productivity  increases 
with  the  availability  of  a standeuxllzed  interface  such  as  GEM. 


The  Facets  qf  GSM 

GEM,  like  most  operating  ^tems,  is  written  in  modules.  In  fact  GEM 
could  actually  be  used  in  place  of  TOS  as  the  basic  operating  ^tem 
for  a computer.  It  supports  a Disk  Operating  System  (GEMDOS),  a 
Virtual  Device  Interface  (VDI),  and  an  ^plication  Environment  Ser- 
vices (AES),  which  collective^  contain  all  the  information  necessary  to 
drive  the  computer.  TOS  contains  functions  and  routines  specific  to 
the  Atari  STs  special  features.  This  is  why  TOS  is  used  with  GEM. 


GEMDOS 

The  Graphics  Environment  Manager  Disk  Operating  System  (GEM- 
DOS) is  the  first  module.  GEMDOS  consists  of  a Basic  Input/Output 
System  (BIOS),  a disk  file  handler,  and  some  useful  intern  fimctlons. 
Tlie  BIOS  provide  routines  for  disk  access  and  primary  communica- 
tion with  the  keyboard,  screen,  and  other  external  devices.  The  disk 
file  handler  keeps  data  organized  on  disks.  GEM  supports  a hierar- 
chical file  structure  using  a primary  (root)  directory  and  folders 
(subdirectories)  much  like  UNIX  and  MS-DOS.  The  system  functions 
provided  under  GEMDOS  Include  disk  access,  date  and  time  setting, 
memory  management  and  process  initiation  and  termination. 


Hie  VDI 

The  second  module  of  GEM  is  the  Virtual  Device  Interface,  referred 
to  as  the  VDI.  The  VDI  is  a standard  graphics  environment  In  which 
to  write  a gr^hics  application.  This  means  that  the  same  VDI  func- 
tions can  be  used  with  a video  display,  graphics  printer,  plotter,  or 
any  other  graphic  device.  This  happens  through  a combination  of 
operations  the  VDI  performs.  The  VDI  consists  of  two  parts:  the 
Graphics  Device  Operating  System  (GDOS)  and  the  device  drivers  and 
face  files.  These  two  parts  work  together  to  make  possible  the  device- 
independent operations  of  GEM. 
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Tile  GDOS  provides  the  device-independent  interface  that  allows 
you  to  use  a standard  set  of  functions  for  generating  graphic  images 
without  being  concerned  about  what  device  the  image  will  be  drawn 
on.  The  GDOS  describes  your  programmed  image  to  a coordinate 
system  that  corresponds  to  the  “ideal”  graphic  device.  This  ideal 
device  is  simply  a standard  set  of  plotting  points  that  can  be  used  to 
correspond  to  the  actual  plotting  points  of  a specific  device.  When  you 
wish  to  output  the  image  to  an  actual  device,  the  image  description 
is  mapped  onto  the  device’s  coordinate  system  through  the  device 
drivers.  The  device  driver  takes  care  of  producing  the  proper  image 
using  the  device’s  capabilities.  If  a particular  feature  is  not  provided 
by  a device,  the  device  driver  will  try  to  emulate  that  feature  as  dosety 
as  possible.  For  Instance,  some  printers  cannot  provide  italicized 
letters  and  underline  the  desired  text  instead.  The  face  files  contain 
a description  of  a particulEur  alphabet  font  that  can  be  easily 
translated  to  any  device.  The  VDI  maintains  GEM’s  device-indepen- 
dent capability  by  allowing  the  same  VDI  functions  to  be  used  with 
any  graphic  device  and  still  produce  approximatdy  the  same  image. 


Ihe  AES 

The  Application  Environment  Services  (AES)  is  a collection  of 
libraries  that  allow  a programmer  to  utilize  the  various  graphic 
images  to  provide  a stwdard  user  interface.  A library  is  a set  of 
commands  that  have  been  grouped  together.  The  AES  manages 
gr£^hics  input  in  much  the  same  way  as  the  VDI  manages  graphics 
output  In  other  words,  the  libraries  of  the  AES  contain  functions  for 
icons,  drop-down  menus,  dialog  boxes,  alert  messages,  windows,  and 
mouse  control  from  a user.  The  GEM  desktop,  the  workspace  provided 
by  the  computer  after  boot  up,  is  an  exEunple  of  a GEM  application 
that  uses  the  AES. 

In  addition  to  the  subroutine  libraries,  the  AES  contains  a limited 
multitasking  kernel  and  dispatcher,  a shell,  a desk  accessory  buffer, 
and  a menu/alert  buffer.  The  subroutine  libraries  contain  the  func- 
tions for  windowing,  controlling  the  mouse,  displaying  q^tem  and 
error  messages,  and  drawing  AES  objects  on  the  screen.  These  func- 
tions are  the  elements  of  the  AES  most  useful  to  a programmer; 
therefore,  they  are  the  focus  of  discussion  of  the  AES. 

Brieffy  then,  the  three  portions  of  GEM  are  GEMDOS,  VDI,  and  AES. 
These  three  components  Interact  to  manage  the  graphics-based  en- 
vironment the  Atari  uses  and  to  make  it  device-independent  Before 
you  learn  to  use  GEM  in  applications  programming,  two  additional 
parts  of  the  operating  system  need  to  be  explained. 
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The  Line  A Handler 


The  second  component  of  TOS  to  be  examined  is  the  Line  A Handler. 
This  is  a set  of  sixteen  functions  that  provide  primitive  routines  for 
graphics  output  to  the  video  display.  These  functions  Include  screen 
initialization,  put  and  get  pixels,  line  drawing,  rectangle  fill,  polygon 
fill,  bit  map  block  transfers,  show  and  hide  mouse,  sprite  manipula- 
tion, and  other  miscellaneous  functions.  The  Line  A routines  provide 
extremely  fast  execution  of  basic  graphic  primitives.  In  fact,  the  VDI 
uses  the  Line  A functions  to  draw  on  the  screen.  Unfortunately,  the 
Line  A routines  are  only  accessible  from  the  assembly  language  level. 
Because  this  book  deals  primarily  with  programming  the  ST  in  C, 
only  a brief  coverage  of  these  routines  is  ^ven  in  Chspter  2. 


The  XBIOS 


The  basic  input/output  functions  of  the  Atari  ST  could  be  handled 
by  GEM  through  GEMDOS.  However,  the  operating  ^tem  provided 
by  GEM  is  designed  to  provide  hardware  independence.  This  means 
that  the  operating  ^tem  has  to  be  a generic  one  that  does  not 
Include  special  features  of  a given  machine,  such  as  sound  and  MIDI 
(musical  Instrument  device  interface).  Also,  because  GEM  uses  device 
drivers  to  translate  its  generic  routines  into  device-specific  informa- 
tion, it  is  slower  and  less  efficient  than  writing  a routine  to  directly 
manipulate  a device.  To  overcome  this  slight  drawback.  Atari  has 
written  the  extended  Basic  Input/Output  System  (XBIOS).  Written 
specifically  for  use  with  Atari  hardware,  XBIOS  provides  access  to  the 
special  features  of  the  machine.  Of  course,  GEM  and  XBIOS  oc- 
casionally overlap  in  functionality.  For  example,  you  can  set  the  date 
and  time  with  either  GEM  or  XBIOS.  In  general,  XBIOS  provides 
access  to  machine-specific  functions  like  sound,  kQrboard  translation 
tables,  MIDI,  and  color  settings. 


What  To  Use 


Atari  has  supplied  a very  basic  operating  ^tem,  TOS,  for  a program- 
mer to  use  in  accessing  the  ST’s  hardware.  GEM,  on  the  other  hand, 
is  a generic  operating  ^tem  with  graphic  support  that  allows  access 
to  many  different  hardware  systems.  Either  of  these  ^tems  could  be 
used  to  write  a program  for  the  ST.  TOS  and  XBIOS  programs  are 
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very  text-oriented  and  their  operations  (for  example,  character  in- 
put/output and  reading/writing  to  disk  by  sectors)  work  at  a rdativety 
low  level.  Working  at  a much  higher  level,  GEM  software  provides  a 
more  natural  view  of  how  a program  needs  to  be  organized.  The 
drawback  to  GEM  is  that  it  does  not  provide  access  to  all  of  the  ST’s 
features  such  as  soimd  and  disk  formatting.  The  question  you  are 
probabty  asking  is  “Which  routines  do  I use?” 

The  answer  is  “It  depends.”  GEM  is  a well-documented,  consistent 
Intern  that  provides  an  excellent  user  interface.  Throughout  this 
book,  GEM  is  used  whenever  possible.  However,  for  some  functions 
you  need  to  use  the  less  flexible  TOS  to  access  special  ST  hardware. 
For  instances  where  you  need  to  use  Atari  XBIOS  functions,  a note 
is  made  that  these  routines  are  not  included  in  GEM. 


Using  GEM 


Programs  that  use  a graphics-based  environment  are  far  easier  for  a 
first-time  user  to  interact  with.  Thanks  to  the  advances  of  PARC, 
.^ple,  and  Atari,  they  are  also  simpler  for  a programmer  to  produce. 
The  ability  to  include  library  graphics  routines  that  provide  easy  user 
interaction  can  save  you  literally  hundreds  of  hours  of  work.  Addi- 
tionally. GEM’S  device-independent  capabilities  allow  you  to  port 
programs  intact  from  system  to  system  and  reproduce  images  on  a 
variety  of  output  devices  without  providing  individual  device  instruc- 
tions. 

In  order  to  be  device-independent,  GEM’s  VDI  is  divided  into  two 
distinct  sections,  the  GEM  interface  and  the  device  drivers.  The 
interface  takes  a program’s  output  and  converts  it  to  a generic 
internal  representation.  The  device  drivers  can  then  take  this  internal 
representation  and  convert  it  to  instructions  for  a specific  output 
device.  The  same  internal  representation  is  used  for  all  devices;  saving 
this  representation  in  a file  frees  you  from  having  to  recreate  the 
image  each  time  it  is  to  be  output  Saving  is  done  through  the  use 
of  metafiles  discussed  in  .^pendix  A. 

The  GEM  interface  can  be  accessed  in  two  ways:  through  assembly 
language  or  through  C function  calls.  Access  through  assembly 
language  is  quite  low  level  and  would  be  used  to  program  device- 
dependent  functions.  This  book  is  concerned  with  programs  that 
utilize  the  flexibility  provided  by  the  ST:  therefore,  the  C function  calls 
are  used. 

The  GEM  VDI  can  be  thought  of  as  one  routine.  This  routine  knows 
how  to  represent  all  the  graphic  images  produced  by  GEM;  it  also 
performs  a wide  variety  of  different  graphics  functions.  To  tell  the 
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routine  what  you  want  done,  use  an  operation  code  (opcode,  for 
short),  which  is  then  passed  to  the  routine. 

Besides  the  opcode,  most  functions  require  a set  of  parameters  that 
define  the  operation.  To  draw  a circle,  for  example,  you  need  to  tell 
the  machine  where  to  put  the  center  point  and  how  long  to  make  the 
radius.  You  suppfy  these  variables  using  x and  y coordinates  to  plot 
the  center  point  and  the  length  of  the  radius  along  the  x axis.  The 
parameters  are  passed  to  the  VDI  fimction  through  a set  of  global 
arrays  (values  assigned  throughout  the  system).  Then  the  VDI  plots 
your  graphics  display. 

There  are  five  global  arrays  of  integers  used  by  the  VDI  functions 
that  must  be  defined  by  your  C program.  These  arrays  include  control 
values,  input  emd  output  integers,  and  input  and  output  vertices  (see 
Table  1-1).  The  control  values  contain  a variety  of  information  such 
as  the  opcode,  the  number  of  elements  contained  in  the  other  four 
arra)ra,  and  the  output  device  number.  The  input  and  output  Integer 
arrays  are  used  to  pass  integer  values  between  the  VDI  routine  and 
the  program  that  uses  them.  The  input  and  output  vertices  arrays 
hold  the  points  to  be  plotted  by  the  VDI  to  create  the  desired  graphics 
display. 


Table  1-1:  Global  Parameter  Attayu  Used 
intbeVDI 


Variable  Name 

* Description 

Number 
of  Elements 

contrl 

Control  values 

12 

intin 

Input  Integers 

128 

ptsin 

Input  vertices 

128 

intout 

Output  int^ers 

128 

ptsout 

Output  vertices 

128 

Because  the  arrays  are  linear  (one-dimensional)  and  a vertex  (a 
point)  requires  two  coordinates,  GEM  has  adopted  a standard  format 
for  storing  points  In  the  array.  For  each  point  the  x coordinate  is 
given  first  foUowed  by  its  corresponding  y coordinate.  Since  aU  arrays 
in  C start  with  element  zero  (0),  the  x cmd  y coordinates  of  the  first  in- 
put point  are  placed  in  elements  intin[0]  and  intin[l],  respectively. 
Those  of  the  second  input  point  are  placed  in  elements  intinl2]  and 
intin[3]. 

It  is  very  time-consuming  and  inefficient  to  have  to  fill  in  eveiy 
pauameter  array  and  call  each  routine  by  number.  However,  there  is 
no  need  to  do  this.  C provides  a set  of  C “bindings”  that  provide  ea^ 
access  to  GEM  as  well  as  Atari  functions.  E^ch  binding  is  merely  a C 
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function  call  Interface  that  allows  }rou  to  call  up  an  entire  VDI  opera- 
tion without  fUllng  In  the  opcode  and  array  elements.  Suppose  you 
want  to  draw  a circle.  The  function  call  for  a circle  In  C Is  named 
y-dideC ).  You  would  only  need  to  suppfy  the  parameters  for  the  x 
and  y coordinates  of  the  center  and  the  length  of  the  radius.  Tlie 
function  fills  In  the  appropriate  elements  in  the  control  and  point 
arrays  for  you.  Hie  M^simax  compiler  defines  many  of  the  function 
names  In  header  files  used  In  the  programs  In  this  book  (see  Appen- 
dix B.  Header  Files). 

The  primary  reason  for  mentioning  these  arrays  Is  that  thqr 
must  be  defined  somewhere  In  your  program.  Ch^ter  3 discusses 
preclsety  how  to  do  this.  Also.  If  you  plan  to  do  any  assembty  language 
programming  with  GEM.  these  parameter  arrays  will  be  the  primary 
form  of  communication  between  your  program  and  GEM.  Throughout 
the  rest  of  this  book,  parameter  arrays  are  merety  mentioned  for 
completenesa  Little  emphasis  Is  given  to  them  unless  required. 

The  AE^  operates  In  a marmer  similar  to  the  VDI.  There  are  seven 
parameter  arrays  for  the  AE^:  global  values,  parameter  blocks,  control 
values.  Input  and  output  Int^ers.  and  input  and  output  addresses 
(see  Table  1-2).  Since  these  arrays  are  already  defined  In  the  AES 
libraries,  you  don’t  need  to  define  them  within  your  program  like  the 
VDI  arrays.  In  general,  you  don’t  need  to  access  the  AES  arrays  for 
your  function  calls.  The  size  of  these  arrays  depends  on  the  im- 
plementation of  the  AES.  Since  you  don’t  need  to  declare  the  arrays, 
you  don’t  need  to  know  their  size.  However,  they  are  ^obal  variables. 
If  you  want  to  access  them,  simpfy  declare  them  as  external  variables 
within  your  program. 


Table  1-2:  caobal  Parameter  Aizays 
Used  In  die  Aral 


Variable  Nome 

Description 

control 

Control  values 

global 

Current  status  values 

inLAn 

Input  Integers 

int-out 

Output  integers 

addrJn 

Input  addresses 

addr^ut 

Output  addresses 

Writing  a C Program 

There  are  many  good  compilers  available  for  the  C language  on  the 
Atari  ST;  we  use  the  Megamax.  Whichever  compiler  you  use,  you 
should  familiarize  yourself  with  how  to  create  simple  programs  with 
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a compiler  before  you  attempt  the  programs  In  this  book.  The 
Megamax  compiler  for  the  Atari  ST  comes  with  an  application 
program  called  SHELL.  PRG.  This  application  provides  a more  con- 
venient programming  environment  than  the  desktop. 

When  writing  a C program,  you  first  need  an  editor  capable  of 
writing  the  program  source  files  (the  code  that  you  write)  in  a 
nonformatted  file.  Source  files  should  not  contain  special  word 
proc^sing  characteristics  but  onty  plain  texL  You  may  name  your 
source  file  anything  you  wish  within  normal  file-naming  parameters 
as  long  as  it  has  the  letter  “C”  as  its  file  extension  (for  example. 
program.c.  source.c.  or  myfile.c 

The  next  thing  you  need  is  a compiler.  Since  different  compilers 
operate  different^,  refer  to  the  compiler  manual  to  determine  proper 
operatlr^  procedures.  With  the  Megamax  compiler,  yon  first  initiate 
the  compiler  program  and  then  enter  the  source  file's  name.  If  you 
are  using  the  shell.  }rou  execute  the  compiler  and  select  the  source 
file  from  the  file  selection  box.  The  source  file  is  processed  (compiled) 
into  an  object  file,  which  is  an  intermediate  form  of  3rour  program. 
The  object  file  has  the  same  name  as  your  source  file,  but  with  the 
letter  “O”  as  its  extension  such  as  program.o.  source.o.  or  myfile.o. 

Finally,  you  need  a linker.  A linker,  as  its  name  implies,  links  files 
together.  In  C.  you  can  create  separate  object  files  that  contain 
different  discrete  functions  of  your  program.  A linker  combines  these 
object  files  into  one  program  file.  Also  called  a binder,  a linker  binds 
your  program’s  references  to  the  operating  ^tem  with  a code  that 
Interfaces  with  the  ^tem.  As  this  code  is  supplied  by  the  compiler 
manufacturer,  you  need  not  be  overly  concerned  with  it  For  the 
Megamax  compiler,  you  initiate  the  linker  and  enter  in  all  the  object 
files  to  be  linked.  Since  the  order  may  be  important,  check  the 
compiler  manual.  If  you  are  using  the  Megamax  shell,  execute  the 
linker,  move  the  appropriate  object  files  to  the  link  list,  and  select  “OK” 
to  begin  Unking.  All  the  programs  in  this  book  use  only  one  source 
file  and  one  object  file;  the  Interface  code  is  automatical^  included  by 
the  Megamax  linker. 

One  other  useful  program  is  a resource  construction  program.  This 
program  creates  resource  files  for  application  programs.  Resource 
files  contain  data  for  dialog  boxes,  alert  boxes,  and  menus  used  by 
the  program.  Resources  and  the  resource  construction  program  are 
discussed  later  with  the  AES. 

Take  time  now  to  read  the  compiler  manual.  Write  and  compile  some 
very  simple  C programs.  Once  you  know  how  your  compiler  works, 
writing  more  elaborate  programs  becomes  easier. 


CHAPTER  TWO 

Picture  This — ^An 
Introduction  to 
Computer  Graphics 


“A  picture  is  worth  a thousand  words.”  If  this  were  not  the  case, 
computer  graphics  might  never  have  become  a reality.  However,  the 
adage  is  true,  and  computer  graphics  has  become  an  industry  unto 
itself.  This  chapter  shows  how  computer  graphics  are  created  and. 
more  specificalfy,  how  the  Atari  ST  generates  graphics  displays.  This 
chapter  also  introduces  various  kinds  of  input  device  commonfy 
used  with  interactive  graphics  ^tems  and  explains  how  these 
devices  work.  All  of  this  is  a preface  to  the  concepts  and  terminology 
used  by  GEM  to  implement  a graphic  interface  that  is  ea^  for  both 
the  computer  operator  and  programmer  to  use. 


Background 

The  realm  of  computer  graphics  covers  a wide  variety  of  devices  and 
techniques.  Just  explaining  the  various  graphic  devices  now  available 
would  take  a book  by  itself.  The  discussion  of  computer  graphics  in 
this  chapter  limits  itself  to  the  Atari  ST  and  its  GEM  environment 

The  Pixel 

Look  closefy  at  the  Atari  ST  screen  after  you  turn  it  on.  From  a 
distance  you  can  see  the  GEM  desktop,  but  up  dose  you  can  see  dots. 
E^ch  dot  is  called  a picture  dement  or  pixel  Your  entire  screen  is 
realty  a grid  or  matrix  of  these  pixds.  FHxels  are  more  visible  on  a 
color  monitor  than  on  a monochrome  monitor  because  the  pixels  are 
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closer  together  on  a monochrome  monitor.  The  closer  together  the 
pixels  are,  the  better  the  quality  of  the  picture  created.  This  difference 
in  pixel  placement  and  picture  quality  is  called  resolution.  An 
example  of  very  low  resolution  would  be  10  dots  per  Inch.  In  this 
mode,  the  ou^ut  device  would  have  onfy  10  dots  to  draw  a line  one 
inch  long.  Naturally,  a plctiue  that  uses  10  dots  for  a line  would  be 
less  well  defined  than  one  that  uses  50  dots  for  the  same  line.  Most 
dot-matrix  printers  provide  a resolution  of  70  to  150  dots  per  Inch. 
Laser  printers,  known  for  their  excellent  resolution,  can  have  as  many 
as  300  dots  per  inch. 

A display  on  a monochrome  monitor  is  created  using  the  two 
different  colors  a pixel  can  display.  These  colors  are  usualfy  black  and 
white,  black  and  amber,  or  black  and  green.  Eveiy  pixel  on  the  screen 
can  display  either  color,  depending  on  whether  It  is  turned  on  or  off. 
On  the  Atari  ST,  an  “on”  pixel  shows  black  and  an  “off”  pixel  shows 
white.  This  "on/ofT  terminology  probabty  reminds  you  of  the  yes/no 
configuration  for  bits  in  computer  memory.  In  fact  the  two  are  dosety 
related.  Creating  the  range  of  hues  available  on  a color  monitor  is  a 
little  more  complex,  but  it  builds  on  the  techniques  used  for  mono- 
chrome monitors.  Color  monitors  are  covered  later  in  this  dieter. 

Display  Technology 

The  first  step  toward  understanding  how  screen  displays  (and  other 
types  of  displaj^)  work  is  to  see  how  a computer  monitor  physical^ 
creates  the  light  for  a white  pixd  (the  “off"  designation  in  the  case  of 
the  Atari).  The  inside  of  the  monitor’s  glass  screen  is  coated  with 
phosphor,  a substance  that  glows  when  an  dectron  (an  dectric  par- 
tide)  hits  it  Screen  monitors  are  equipped  with  dectron  guns  which 
project  dectrons  onto  the  screen.  When  an  dectron  hits  a point  on 
the  screen,  a white  dot  shows.  The  phosphor  glows  for  only  a fraction 
of  a second;  to  keep  a dot  glowing  continuously,  the  gun  creates  a 
beam  of  dectrona  There  are,  of  course,  many  dots  on  a screen  that 
must  be  lit  to  create  a sin^e  display.  Since  it  would  be  impractical  to 
have  an  dectron  gun  corresponding  to  eveiy  pixd  on  your  screen,  the 
gun's  beam  scans  across  the  screen  line  by  line.  When  the  beam 
reaches  the  bottom  comer,  it  moves  back  to  the  opposite  comer  on 
top  and  starts  the  process  all  over  again.  This  happens  veiy  quickfy; 
scanning  the  entire  screen  takes  about  one  sixtieth  of  a second. 

As  the  beam  scans  the  screen,  it  turns  on  for  each  dot  that  should 
be  glowing  and  off  for  each  dot  that  should  be  dark.  The  question 
now  arises.  “How  does  the  computer  know  which  pixels  are  on  and 
which  are  off.  emd  how  does  it  remember  from  one  pass  to  the  next?” 
It’s  rather  simple,  really.  The  computer  uses  its  memory.  Actualfy,  it 
uses  a portion  of  its  memory  to  create  a map  of  each  pixd’s  position 
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on  the  screen.  For  each  bit  in  memory  set  to  1,  the  corresponding 
pixel  is  considered  in  the  "on”  state.  For  each  bit  set  to  0,  tiie  pixel 
is  considered  off.  As  the  dectron  beam  scans  the  screen,  the  display 
hardware  reads  the  memory  and  controls  the  beam  output  This  type 
of  display  architecture  is  called  a bit-mapped  display  because  the 
individual  pixels  are  mapped  to  bits  in  memory. 

Using  a Bit  Map 

The  portion  of  memory  labeled  the  bit  map  is  reserved  for  use  by  the 
display  processor.  The  bit  m£q>  may  actualfy  be  located  anywhere  in 
memory  as  long  as  the  display  processor  knows  where  the  bit  map 
begins.  To  facilitate  this,  the  base  address  of  the  bit  map  must  be 
loaded  into  the  display  processor.  The  Atari  ST  XBIOS  provides 
routines  to  load  the  dl^lay  processor  with  the  bit  map’s  base  address. 
These  functions  are  covered  later. 

To  use  the  display  bit  map  to  create  graphics,  place  a bit  within  the 
map.  The  corresponding  pixel  will  immediately  be  plotted  on  the 
screen.  This  is  a very  direct  approach  to  generating  graphics,  and  it 
is  not  usually  used.  The  advantages  of  this  approach  are  that  it  is  a 
very  fast  access  method  and  it  gives  the  programmer  direct  control 
over  what  is  displayed  on  the  screen.  The  disadvantages  include  the 
fact  that  the  programmer  is  responsible  for  much  additional  process- 
ing overhead  and  that  the  bit  map  display  is  only  practical  for  the 
screen.  This  method  is  completely  device-dependent 


Making  Pictures 


Instead  of  dlrectfy  accessing  the  bit  map.  a set  of  commands  can  be 
used  to  draw  gmphic  objects  such  ais  a point  a line,  or  a rectangle. 
These  routines  do  not  usually  Include  very  complex  objects  like 
circles,  ellipses,  or  houses.  Instead,  the  basic  objects  are  used  as 
foundations  to  build  more  complex  Images.  These  images  are  then 
implemented  in  the  output  hardware  or  through  some  extremely 
efficient  software.  If  this  were  not  the  case,  the  job  of  drawing  more 
complex  objects  would  be  terribly  slow  and  extremely  tedious  because 
you  would  need  to  place  every  dot  in  its  exact  place. 

One  set  of  graphics  routines  available  on  the  Atari  ST  is  called  the 
Line  A Handler.  Atari  engineers  have  utilized  the  Motorola  68000 
microprocessor’s  unimplemented  instructions  to  provide  "quick-and- 
dirty”  access  to  assembler-level  graphies  routines.  The  Atari  ST 
documentation  states  that  "if  an  ^plication  only  needs  a few  primi- 
tive graphics  functions  (and  wants  maximum  performance),  then 
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Line  ‘A’  is  sufficient  (and  optimal).”  In  case  you’re  wondering  about 
the  name  Une  A it  comes  from  the  fact  that  the  68000’s  unimple- 
mented Instructions  all  begin  with  the  hexadecimal  digit  “A”,  llie 
GEM  VDI  provides  most  of  the  functions  foimd  in  the  Line  A Handler. 
In  fact  the  VDI  uses  Line  A for  many  of  its  routines  and  VDI  routines 
are  easily  accessible  using  most  programming  languages.  Because 
direct  access  to  the  Line  A routines  is  available  onfy  through  assembly 
language,  we  do  not  discuss  the  Line  A Handler  b^nd  what  has  been 
presented  here.  If  you  are  interested  in  directly  accessing  the  Line  A 
routines,  you  need  a book  on  68000  assembty  programming  and  the 
Atari  documentation  for  the  Une  A routines. 

GEM  VDI  provides  a programmer  with  a wide  variety  of  high-level 
grs^hics  operations.  For  instance,  you  can  draw  circles,  dllpses.  rec- 
tangles. polygons,  and  arcs.  You  can  also  fill  any  closed  polygon  you 
draw,  not  just  with  blade  dots  but  with  any  type  of  pattern  you 
specify.  You  can  even  draw  lines  and  text  in  various  patterns  simply 
by  specifying  the  pattern  you  want  and  using  the  proper  VDI  fimc- 
tiona 

The  bit  map  and  the  VDI  are  two  separate  entities.  The  VDI  uses  a 
bit  map  to  generate  a graphics  display.  The  VDI  provides  the  interface 
between  the  program  and  the  bit  map.  The  VDI  also  provides  the 
interface  from  the  bit  map  to  graphics  devices  that  may  or  may  not 
use  bit  maps.  For  example,  a plotter  or  dot-matrix  printer  does  not 
have  the  same  capabilities  as  a video  monitor.  A plotter  or  printer 
cannot  place  a dot  on  paper  and  then  remove  it  Once  a dot  is  placed 
on  the  page,  it  is  there  to  stay.  For  these  devices,  you  would  use  the 
VDI  to  draw  an  image  and  then  tell  the  VDI  to  output  the  image  to 
the  device.  Unlike  the  bit  map  for  the  Atari  ST  screen,  you  do  not  have 
access  to  the  internal  VDI  representation  for  other  dedces. 


Uses  of  a Bit  Bliy 

The  concept  of  a bit  map  is  a quite  powerful  one.  First  consider  that 
a bit  map  can  be  any  size  to  accommodate  various  tasks.  If  the  bit 
map  is  being  used  as  the  storage  representation  for  a monitor,  the 
map  will  contain  enough  bits  to  represent  each  pixel.  However,  there 
are  also  smaller  bit  maps  available  from  the  Atari  system.  Suppose 
you  had  a small  bit  map  that  was  16-by-16  bits  in  size.  What  would 
you  use  such  a bit  map  for?  One  possibility  is  illustrated  in  Figure 
2-1.  In  this  bit  msq).  each  1 bit  is  a black  pixel  and  each  0 bit  is  a 
white  pixel.  (The  Atari  inverts  the  usual  1-on/O-off  representation 
because  it  uses  black  images  on  a white  background.)  The  configura- 
tion in  the  illustration  forms  a checkerboard  pattern  (Figure  2-1).  If 
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Figure  2-1  IG-by-lG  Bit  Blap  for  Cheekeiboaid  Pattern 

you  store  a small  bit  map  like  this  in  memory,  you  can  use  it  to  fill 
a rectangle  or  other  closed  polygon  by  copying  it  over  and  over  until 
the  shape  is  filled.  Transferring  data  from  one  place  in  memory  (the 
pattern  bit  map)  to  another  place  in  memory  (the  screen  bit  map)  is 
much  faster  than  calculating  how  to  fill  in  the  rectangle  with  a 
complex  pattern.  Therefore,  one  use  for  small  bit  maps  is  pattern 
definition  for  area  fill. 

Now  look  at  Figure  2-2  where  dots  have  been  used  in  place  of  zeros 
to  make  the  image  more  visible.  Does  the  image  look  familiar?  This 
bit  map  is  a representation  of  the  icon  used  by  the  desktop  to 
represent  a data  file.  A 32-by-32  bit  map  is  used  to  store  icon  Images 
(Figure  2-2).  Instead  of  redrawing  the  icon  each  time  it  is  needed,  a 
program  can  simply  copy  the  icon's  bit  image  into  the  screen’s  bit 
map. 

A third  use  for  bit  maps  is  text  appearance.  EJveiy  character  on  the 
keyboard  can  be  stored  in  an  array  of  bits  called  a character  cell.  If 
you  are  familiar  with  word  processing  or  typesetting,  you  are  probably 
aware  that  text  has  some  characteristics  unique  to  its  representation 
such  as  fonts  or  typefaces,  type  styles,  and  t^  size.  The  terms /ont 
and  typeface  are  ^onymous  and  refer  to  the  look  of  the  letters.  Some 
examples  of  fonts  or  typefaces  are  Reman,  Script,  and  Futura.  The 
type  style  refers  to  modifications  on  the  typeface.  These  Include 
options  such  as  ttalidzation,  imderlinlng,  atottovi&S.  and  boldface. 
The  type  size,  as  the  term  implies,  indicates  how  large  the  letters  are. 
GEM  VDI  allows  you  to  set  the  type  size  in  coordinate  units  (using 
pixel-to-plxel  distance  such  as  20  units  high)  or  in  points  (using 
the  printer’s  measurement  of  1/72  of  em  inch). 
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Figure  2-2  32-by-32  Bit  Map  for  Data  File  Icon 

For  each  character  in  a font  which  generally  Includes  all  characters 
on  the  keyboard,  a character  ceU  needs  to  be  defined.  Each  type  stjde 
must  also  be  defined  in  individual  character  cells  for  every  font  that 
will  use  that  style.  In  addition,  for  each  different  type  size  a new  set 
of  character  cells  for  each  font  and  st^e  needs  to  be  created.  Although 
software  algorithms  exist  to  enlarge  typefaces  and  change  type  styles 
given  a base  font  the  characters  never  look  as  good  as  those  created 
from  character  cells.  This  means  that  an  ambitious  person  needs  to 
program  the  cells  for  each  font  style,  and  size  needed. 

There  are  a number  of  variables  that  can  be  set  for  each  character 
cell.  These  have  to  do  with  the  width  and  height  of  the  individual 
characters  and  the  cells  that  contain  them.  EJach  character  is  as- 
signed a cell  which  determines  how  much  space  a character  occupies 
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and  how  much  space  is  left  around  It  (between  it  and  other  charac- 
ters). Vertically,  each  cdl  is  divided  six  lines.  These  lines  that  start 
at  the  top  and  go  down  are  called  the  top  line,  the  ascent  line,  the 
half  line,  the  base  line,  the  descent  line,  and  the  bottom  line  (see 
Figure  2-3).  Bottom  and  top  lines  define  the  vertical  limits  of  a single 
cell,  or  the  cell  height  The  bottom  line  of  one  cell  in  a block  of  text 
is  usually  defined  as  the  top  line  of  the  cell  directly  below  it  The 
characters  in  most  cases  do  not  use  the  total  available  cell  height 
Rather,  th^  extend  up  to  the  ascent  line  if  thqr  are  full-sized  letters 
(upper-case  or  tall  lower-case  letters)  down  to  the  descent  line  if 
they  must  extend  below  the  beise  line  (as  with  lower-case  letters  such 
as  “g”  and  “j”).  The  half  line  defines  the  maximum  height  for  most 
lower-case  letters  and  small  characters,  and  the  base  line  defines  the 
bottom  of  a character. 
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Figure  2-3  Character  Cell 


Defining  the  width  of  characters  and  character  cells  is  somewhat 
similar  to  defining  the  height  where  the  character  width  Is  usually 
less  than  the  cell  width.  This  allows  for  space  between  characters.  The 
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actual  commands  used  to  define  typefaces,  type  styles,  and  type  sizes 
are  discussed  later  in  this  book.  For  now,  it  is  important  to  realize 
that  each  character  cell  is  a small  bit  map  that  can  be  called  up 
instantty  from  memoiy  for  use  in  a display. 


Logic  Operators 


Basic  logic  operations  performed  in  memoiy  are  used  to  change  pixel 
values.  Logic  operations  act  on  the  values  true  and  false.  In  computers, 
these  values  must  be  translated  into  the  binaiy  values  1 and  0.  For  the 
purposes  of  this  discussion,  let  true  have  the  value  of  1 and false  have 
the  value  of  0.  Logic  operators  work  in  much  the  same  way  as  mathe- 
matical operators.  The  operator  takes  two  operands  (values),  performs 
an  operation  on  them,  and  produces  a result  The  four  logic  operators 
commonty  used  with  computers  are  OR,  AND,  XOR,  and  NOT. 

The  first  operator,  OR,  tests  If  either  of  its  two  operands  is  true 
(equal  to  1).  If  that  condition  is  met  the  operation  gives  a result  of 
true.  If  both  operands  are  false  (equal  to  0),  the  operation  gives  a 
result  of  false.  Table  2-1  is  the  logic  table  for  OR  The  x and  y columns 
refer  to  the  two  operands.  The  r^ult  is  listed  in  the  x OR  y column. 

Table  2-1:  Logic 
Table  for  OR 


X y X OR  y 

T T T 

T F T 

FT  T 
F F F 


The  next  operator,  AND.  tests  if  both  of  two  operands  are  true  (equal 
to  1).  If  this  condition  is  met  the  operation  gives  a result  of  true.  How- 
ever, if  either  operand  has  a value  of  false  (equal  to  0),  the  entire  opera- 
tion gives  a result  of  false.  Table  2-2  shows  the  logic  table  for  AND. 

Table  2-2:  Logic 
Table  for  AND 


X y xAND y 

T T T 

T F F 

FT  F 

F F F 
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The  third  operator.  XOR,  is  quite  useful  when  dealing  with  graphics. 
The  XOR  operator  produces  a true  result  if  the  two  operands  have 
different  values.  In  other  words,  if  x and  y are  different  values,  the 
operation  tests  true.  If  they  are  the  same  value,  the  operation  tests 
false  (see  Table  2-3).  The  interesting  aspect  about  XOR  is  that  it  acts 
like  a toggle.  If  you  have  a value  and  XOR  it  with  some  arbitrary  value, 
3T0U  get  some  result.  If  you  XOR  this  result  with  your  original  value, 
you  get  the  original  arbitrary  value  back.  For  example,  if  you  have  the 
value  1 and  XOR  it  with  0,  the  result  will  be  1.  If  you  XOR  this  result 
of  1 with  your  original  value  of  1.  you  get  back  0.  An  example  of  how 
this  is  useful  is  given  soon. 


Table  2-3:  Lo|^c 
Table  for  XOR 


X y xXORy 

T T F 

T F T 

FT  T 
F F F 


The  last  operator,  NOT,  is  a unary  operator.  This  means  that  it 
onfy  uses  one  operand.  NOT  Inverts  the  value  of  the  given  operand  so 
that  NOT  true  yields  false  and  NOT false  gives  a true  result 
The  logical  operators  are  essential  to  the  creation  of  graphics 
displays.  They  are  used,  in  some  aspect  in  every  graphics  operation. 


Writing  Modes 


In  the  initial  discussion  of  bit  maps  and  the  VDI,  it  was  stated  that 
certain  writing  modes  available  with  the  bit  maps  would  have  mini- 
mal effect  on  a program  output  to  the  screen.  This  section  explains 
the  four  writing  modes  available  from  the  Atari  for  use  with  bit  map 
displays.  Writing  modes  are  methods  of  taking  bit  maps  from  memory 
and  plotting  them  onto  the  bit  map  for  the  screen  display.  The  four 
modes  available  from  the  Atari  are  replace,  transparent,  XOR  and 
neocrse  transparent  Like  the  examples  given  above,  the  writing  modes 
use  two  bit  maps:  a source  bit  map  held  in  memory  and  a target  bit 
map  that  is  normally  the  screen. 

The  simplest  of  the  writing  modes  to  understand  is  replacement  In 
this  mode,  each  bit  in  the  source  map  has  a corresponding  bit  in  the 
target  map.  The  bits  are  slmpty  transferred  from  the  source  to  the 
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target  ma^.  Thus.  If  you  have  a 0 bit  In  the  first  position  of  the  source 
map,  the  first  position  In  the  target  map  also  becomes  a 0. 

For  the  remaining  modes,  the  source  bit  map  and  the  target  bit 
maq>  go  through  a logic  operation  with  the  result  placed  in  the  target 
bit  map.  For  example,  in  transparent  mode  the  pixels  set  to  1 in  the 
source  bit  map  are  copied  to  toe  corresponding  bit  in  the  target  bit 
map.  Those  pixels  that  are  0 in  toe  source  bit  map  have  no  effect  on 
toe  target  bit  map. 

In  XOR  mode,  each  bit  In  toe  source  map  and  toe  corresponding 
pixel  in  toe  target  bit  msq>  go  through  toe  logical  operation  XOR 
explained  above.  If  you  have  a 1 bit  in  toe  source  map  and  a 1 bit  in 
the  target  bit  map.  toe  pixel  in  target  bit  map  is  set  to  0.  If  you  have 
a 1 in  the  source  bit  map  and  a 0 in  toe  target  bit  map,  the  resulting 
pixel  in  toe  target  bit  ms^  is  a 1. 

The  final  writing  mode  available  from  the  Atari  ST  is  reverse 
transparent  mode.  This  mode,  as  its  name  suggests,  works  in  a 
manner  exactly  opposite  from  toe  transparent  mode.  In  other  words, 
when  a bit  has  the  value  0 in  the  source  bit  map,  the  corresponding 
pixel  in  the  target  bit  map  is  set  to  1.  The  descriptions  given  here  for 
bit  maps  and  writing  modes  apply  primarily  to  monochrome  monitors. 
The  use  of  these  writing  modes  is  explored  shortly. 


Bit  Map  Representation 


The  use  of  bit  maps  for  icons  and  text  representation  assumes  that 
the  source  and  target  bit  maps  are  the  same  size.  In  reality,  the  VDI 
and  most  graphics  applications  use  this  function  by  having  two 
d^erent  sizes  of  bit  map&  For  example,  an  icon  bit  map  that  consists 
of  a 32-by-32  bit  square  is  not  toe  same  size  as  a monochrome  screen, 
which  consists  of 640-by-400  bits.  The  bit  map  is  memory  for  the  icon 
is  used  as  a mask  on  top  of  toe  bit  map  for  the  screen.  1^  locating  toe 
upper  left-hand  comer  pixel  on  toe  screen,  toe  bit  map  of  the  icon 
can  be  overiayed  onto  the  bit  map  of  the  screen. 

This  sounds  quite  simple,  but  toe  actual  representation  of  a bit 
map  is  a little  more  complex.  Memory  itself  is  linear:  one  bit  follows 
another  bit  and  thus  creates  bytes  (eight  consecutive  bits),  words,  and 
so  on.  A bit  map  is  more  of  an  array  with  height  as  well  as  width.  As 
in  memory,  each  bit  in  the  bit  map  is  contained  in  a byte.  These  bytes 
are  arranged  in  lines  along  the  map.  When  the  computer  reaches  the 
end  of  a line  in  the  bit  map,  as  it  is  recording  the  map  in  memory,  it 
slmpty  continues  to  toe  next  line  in  toe  map.  All  this  is  handled  by 
toe  VDI  and  is  discussed  in  more  detail  later  in  toe  book. 
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Output  Devices 

Obviousty,  not  all  output  devices  are  the  same.  Differences  between  a 
screen  and  a printer  have  already  been  demonstrated  through  the 
single  example  of  the  use  of  the  bit  map.  Output  devices  also  vary 
within  the  same  category.  For  Instance,  a color  monitor  has  very 
different  needs  and  capabilities  from  a monochrome  monitor.  Even  a 
monochrome  monitor  can  come  in  a variety  of  display  modes:  bit  map 
display,  vector  display,  and  storage  tube  display.  Devices  that  produce 
so-called  hard  copy  also  differ  widely  in  their  capabilities.  Plotters, 
laser  printers,  and  dot-matrix  printers  all  use  different  modes  to 
produce  output  and  there  is  a great  deal  of  variety  within  each  of 
these  different  types.  Plotters  can  use  a bit  map,  a pen,  or  a drum  to 
place  an  image  on  paper.  In  some  cases  when  preparing  a graphics 
operation,  the  programmer  needs  to  consider  how  the  image  is 
produced.  For  example,  a pen  plotter  that  uses  a pen  to  draw  lines 
does  not  use  a bit  map  to  coordinate  the  lines.  A bit-mapped  screen, 
however,  does  use  a bit  map.  A dot-matrix  printer  can  translate  a bit 
map  from  memory  to  output  on  paper;  however,  it  must  go  through 
some  changes  because  a dot-matrix  printer  prints  seven  or  more  dots 
vertically  at  one  time,  while  the  bit  map  is  arranged  horizontalty. 
Although  GEM  does  quite  well  in  eliminating  these  problems,  some 
consideration  still  has  to  be  given  to  output  especially  for  programs 
that  are  more  complex. 

There  are  some  advantages  and  disadvantages  to  the  capabilities  of 
the  different  devices.  The  bit-msqrped  screen’s  great  advantage  comes 
from  the  writing  modes.  These  make  it  possible  for  a program  to  erase 
or  show  any  pixel  in  any  position  on  the  screen  vlrtualfy  at  any  time. 
This  capability  allows  a programmer  to  create  representational 
graphics  such  as  those  used  in  design  and  animation.  Disadvantages 
include  the  fact  that  the  resolution  of  the  screen  is  limited  to  the 
number  of  pixels  the  screen  can  display.  For  example,  if  you  cormected 
the  Atari  to  a television  set  the  ch^cters  are  far  less  readable  than 
those  on  the  monochrome  monitor. 

A vector  display  creates  output  with  an  electron  gun,  just  like  the 
bit-mapped  display.  However,  with  the  vector  display  the  gun  draws 
lines  rather  than  points.  To  obtain  a line,  you  specify  the  start  point 
and  endpoint  This  creates  superb  lines  that  can  be  used  together  to 
produce  high  quality  graphics.  The  disadvantage  is  the  amount  of 
time  it  takes  to  create  the  lines.  The  overhead  with  this  type  of 
graphics  display  is  such  that  the  number  of  lines  you  can  include  for 
any  one  image  is  limited. 

Storage  tube  displajrs  work  in  a manner  almost  identical  to  vector 
displays.  The  exception  is  that  once  a line  is  drawn  to  the  screen,  it 
remains  visible  imtU  the  entire  screen  is  erased.  Therefore,  If  you 
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draw  something,  the  only  way  to  get  rid  of  it  is  to  get  rid  of  your  entire 
display.  This  has  some  obvious  disadvantages  in  terms  of  the  flexibil- 
ity of  the  display.  If  you  want  to  change  a single  line,  you  have  to  erase 
the  display  and  redraw  it  without  that  line.  However,  if  you  are  ready 
for  final  output,  this  type  of  device  can  provide  extremely  fine  images. 

Plotters  have  problems  similar  to  those  found  with  the  vector  and 
storage  tube  displays.  A pen  plotter  acts  like  a vector  display  in  that 
you  put  the  pen  down  where  you  want  to  start  drawing  a line  and  lift 
it  at  the  end.  While  pen  plotters  have  very  good  resolution,  they 
require  much  time  overhead  to  create  images.  Also,  once  a line  is 
drawn,  the  only  way  to  get  rid  of  it  is  to  use  a new  sheet  of  paper. 

Printer  types  can  basically  be  split  into  two  groups:  impact  and 
nonimpact  printers.  The  impact  printers  include  letter-quality  (such 
as  a dal^  wheel)  and  dot-matrix  printers.  Nonimpact  printers  include 
ink-jet;  thermal,  and  laser  printers.  Printers  that  produce  only  letter 
fonts,  such  as  daisy  wheels,  are  almost  useless  in  terms  of  graphics 
output  unless  you’re  interested  in  making  pictures  of  the  Mona  Lisa 
using  Xs.  Most  people  using  this  book  have  a dot-matrix  printer. 
Dot-matrix  printers  use  a set  of  seven  or  more  pins  to  place  patterns 
of  dots  that  create  gr£^hics  displays  on  paper.  Laser  printers  work  on 
much  the  seune  principle  as  a bit-mapped  display.  The  image  is 
created  by  tiny  beams  of  light  that  are  projected  in  patterns  as  defined 
in  a bit  map;  these  form  the  graphics  display. 


Device  Coordinates 


When  you  graph  an  image  on  a piece  of  graph  paper,  you  place  points 
on  a grid  according  to  their  coordinates.  On  a computer  you  must 
also  specify  where  you  want  your  points  placed.  This  is  done  on  a 
two-dimensional  surface  called  a drawing  plane.  The  drawing  plane 
is  simply  a concept  that  provides  an  imaginary  surface  to  draw  on. 
Just  as  with  graph  paper,  the  drawing  plane  can  have  any  type  of 
coordinate  ^tem  you  choose.  For  example,  you  can  use  the  standeird 
Cartesian  coordinate  ^tem.  In  this  ^tem,  the  point  (0,0)  is  placed 
in  the  center;  positive  values  increase  as  you  go  up  and  to  the  right; 
and  negative  values  increase  as  you  go  down  and  to  the  left.  You  can 
choose  a system  where  the  point  (0,0)  is  in  the  lower  left  comer  and 
use  only  positive  coordinates.  You  can  also  place  the  point  (0,0)  in  the 
upper  left  comer  and  have  positive  values  increase  as  you  go  down 
and  to  the  right  This  last  coordinate  system  is  the  one  most  com- 
monly foimd  on  computer  displays,  particulaify  bit-mapped  displays. 
The  reason  for  this  Is  that  the  electron  gun  scans  from  top  to  bottom 
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and  from  left  to  right;  thus  the  bit  map  should  follow  this  order  for 
efficiency. 

The  device  coordinates  you  use  are  dependent  on  how  high  the 
resolution  is  on  the  output  device  you  are  using.  Most  of  the  time, 
device  coordinates  are  represented  with  whole  numbers  (for  example. 
1,  2,  or  3).  These  numbers  specify  some  position  on  the  page  or 
screen,  and  the  range  varies  according  to  the  device  you  are  writing 
to  (for  example,  0-400  or  0-4000).  E>weiy  device  has  its  own  set  of 
coordinates,  most  of  which  start  at  zero  (0).  Some  devices,  such  as 
screens  and  plotters,  allow  you  to  access  any  point  at  any  time.  Other 
devices  are  able  to  move  in  onfy  one  direction;  for  example,  since  most 
printers  can  onfy  move  down  the  page,  your  image  must  be  drawn 
line  by  line.  Thus,  on  a printer  your  device  coordmates  consist  of  the 
line  number  on  a page  and  the  dot  number  on  a line.  On  a screen  or 
plotter  the  coordinates  consist  of  the  actual  horizontal  and  vertical 
positions.  These  coordinates  will,  of  course,  vaiy  from  output  device 
to  output  device. 


Monoduome  Versus  Color  Screens 


When  you  are  dealing  with  monochrome  graphics,  you  can  either  have 
black  or  white;  this  corresponds  quite  nicely  to  the  yes/no  or  0/1  logic 
computers  use.  When  you  use  color  graphics,  you  encounter  a whole 
new  range  of  problems. 

All  colors  can  be  created  using  the  three  primaiy  colors  of  light: 
blue,  green,  and  magenta  (red).  The  presence  of  all  three  colors  at  once 
gives  you  white  and  the  absence  of  any  color  gives  you  black.  If  you 
add  green  and  magenta,  you  get  amber  (yellow/orange).  If  you  add 
green  and  blue,  you  get  aquamarine.  If  you  add  blue  and  magenta, 
you  get  purple.  Other  shadings  and  nuances  are  achieved  by  varying 
the  intensities  of  the  light  colors  being  mixed. 

The  technical  aspects  of  color  representation  Include  the  use  of 
three  electron  guns  Instead  of  the  single  gun  used  in  monochrome 
display.  E^ch  gun  activates  a different  color  of  phosphor:  magenta, 
green,  or  blue.  Combining  the  output  from  the  three  guns  creates 
color  displays  on  your  color  monitor.  To  control  which  colors  are 
activated,  you  must  have  at  least  three  bits  where  one  is  for  magenta, 
the  second  is  for  blue,  and  the  third  is  for  green.  You  can  then  have 
eight  different  color  representations  ranging  from  black  to  white  sim- 
ply by  combining  these  three  bits  in  different  combinations.  To  allow 
an  even  greater  range  of  color,  a fourth  bit  can  be  added  to  adjust  the 
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intensity  of  the  color.  This  gives  you  eight  low-intensity  and  eight 
high-intensity  colors. 

Another  way  of  handling  color  is  to  allow  the  individual  colors  to 
vaiy  their  intensity.  To  do  this,  you  use  one  b3rte  in  memory  to 
determine  the  intensity  of  a particular  gun  for  a particular  pixel. 
Thus,  if  you  have  an  8-bit  byte,  you  can  have  256  intensities.  If  you 
have  three  bjrtes  of  magenta,  blue,  and  green  each  with  256  inten- 
sities, you  have  a range  of  over  16  million  different  color  represen- 
tations per  pixel  However,  to  represent  this  range  you  must  have 
three  bytes  of  memory  per  pixel.  For  the  Atari  ST,  this  means  that 
in  medium  resolution  (320  400  pixels),  you  must  have  over 

350,000  bytes  (350KB)  Just  to  take  care  of  the  color  representation. 
That's  not  a very  efficient  or  logical  use  of  memory. 

To  reduce  this  memory  requirement  the  Atari  uses  color  planes.  In 
essence,  each  of  these  planes  is  the  bit  map  for  a color.  In  low 
resolution  mode  there  are  four  planes;  in  me^um  resolution  there 
are  two  planes;  and  in  high  resolution  (used  onfy  in  monochrome) 
there  is  only  one  plane  because  the  only  colors  represented  are  black 
and  white  (0  or  1).  In  the  color  modes,  the  computer  combines 
corresponding  pixels  In  each  plane  to  obtain  a binary  number  which 
is  then  mapped  to  a color,  llie  Atari  is  capable  of  displaying  512 
different  colors.  However,  because  in  low  resolution  the  maximum 
number  of  bits  available  is  four  (one  for  each  of  the  four  planes),  the 
maximum  number  of  colors  available  for  display  at  any  one  time  is 
sixteen.  There  are  ways  arotmd  this  limitation  that  use  advanced 
graphic  techniques.  For  most  uses,  though,  sixteen  colors  should  be 
enough. 

If  you  go  into  your  control  panel  accessory  in  the  desktop,  you  see 
three  slide  bars  on  the  left  On  a color  monitor  each  bar  rqrresents 
one  of  the  three  colors;  magenta,  blue,  or  green.  By  moving  the  slide 
bar  to  the  top,  you  get  maximum  intensity.  Movl^  the  slide  bar  to 
the  bottom  gets  you  zero  intensity  in  the  particular  color.  There  are 
eight  different  intensities  for  each  color.  If  you  multiply  the  eight  red 
intensities  by  the  eight  blue  intensities  by  the  eight  green  intensities, 
you  get  a total  of  512  color  combinations  available.  On  the  bottom  of 
the  control  panel  are  16  squares.  On  a monochrome  monitor  there 
is  one  white  and  15  black  squares.  On  a color  monitor  each  square 
shows  one  of  the  available  colors.  This  is  your  color  palette,  which 
the  system  uses  by  default  There  is  a table  in  memoiy  that  m£q)s  the 
values  0 through  15  (the  16  colors  in  your  palette)  to  16  of  the  512 
available  colors.  You  can  have  any  combination  of  colors  you  desire, 
and  }TOu  always  have  16  colors  available. 

The  use  of  color  in  a program  requires  a full  imderstandlng  of  the 
color  palette  and  its  construction.  Further  discussion  of  color  graphics 
is  in  Chapter  6. 
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Input  Devices  

Just  as  there  are  many  different  types  of  output  devices,  so  there  are 
a variety  of  input  devices  available  for  use  with  computers.  These  can 
be  generally  broken  down  into  four  basic  categories:  kqfboards, 
locators,  valuators,  and  buttons.  Probably  the  most  familiar  is  the 
keyboard,  a device  for  entering  text  A locator  is  a device  for  pointing 
to  an  object  or  line  of  text  shown  on  a screen.  The  most  common 
locator  is  a cursor,  which  can  be  controlled  by  various  physical 
devices.  The  third  input  device,  a tmluator,  is  a logical  device  that 
provides  a range  of  numeric  Inputs,  for  instance,  a dial  or  a slide  bar. 
Finally,  a button  is  a device  for  selecting  from  a number  of  different 
displayed  options.  These  are  the  logical  or  conceptual  input  devices. 
The  physical  Implementations  of  these  are  explained  below. 

The  function  of  the  keyboard  as  an  input  device  has  come  to  be 
taken  for  granted.  It  is  a layout  of  letters  and  specialized  characters 
produced  on  the  screen  by  pressing  the  character's  corresponding 
key.  It  is  almost  identical  to  the  function  of  a typewriter's  keyboard. 
Another  way  a kqrboard  can  be  implemented  is  to  represent  the 
keyboard  on  the  screen  and  use  a locator  to  identify  the  k^  to  be 
entered. 

Locators  are  relatively  new  liq>ut  devices  for  personal  computers. 
The  most  widely  used  physical  locator  is  the  mouse,  which  usually 
consists  of  a small  box  containing  a roller  ball.  The  mouse  controls 
cursor  movement  on  the  screen.  Other  locators  include  devices  such 
as  ll^t  pens,  which  physically  point  at  an  object  on  the  screen. 
Joysticks  are  a third  type  of  locator;  like  a mouse,  they  move  the 
cursor  on  the  screen. 

The  valuator  is  usually  implemented  as  a dial  or  a slider.  The  user 
can  change  the  position  of  the  valuator  and  cause  a new  value  to  be 
produced.  This  value  can  represent  anything  from  sound  volume  to 
one  coordinate  of  the  cursor's  position. 

The  last  logical  input  device,  the  button,  is  usually  just  a button.  A 
button  is  often  found  in  combination  with  locators.  For  Instance,  in 
addition  to  the  tracking  ball  the  mouse  box  usually  has  at  least  one 
button,  which  can  be  used  to  select  information  on  the  screen. 
Joysticks  also  usually  have  buttons  that  provide  some  type  of  input 
to  the  screen,  depending  on  the  software  being  Implemented.  Func- 
tion keys  are  yet  another  type  of  button.  They  are  most  often  included 
on  the  keyboard  but  may  be  physlcalfy  located  away  from  the  usual 
character  set.  They  are  identified  by  the  letter  F followed  by  a number, 
usually  1 through  10.  These  buttons  are  quite  special,  as  they  change 
their  function  depending  upon  what  program  you  are  running  and 
where  In  that  program  you  are.  They  are,  therefore,  referred  to  as 
programmable  function  keys. 
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Implementing  Logical  Devices 


On  the  Atari  ST,  a mouse  is  used  as  the  locator.  Valuators  can  be 
taken  from  the  keybosuxj  or  from  an  object  on  the  screen  (for  example, 
the  slide  bars  on  the  windows).  Buttons  on  the  Atari  Include  the 
function  kq^  at  the  top  of  the  k^oard,  the  buttons  on  the  mouse, 
and  particidar  keys  on  the  keyboard  (depending  on  how  th^  have 
been  programmed  for  application).  The  keyboard,  of  course,  acts  like 
a normal  keyboard  unless  you  program  it  otherwise. 


The  Ideal  Graphics  Device 


A concept  much  referred  to  in  computer  graphics  is  the  ideal 
graphic  device.  This  is  not  an  actual  ph3rsical  output  device.  Rather, 
it  is  a concept  that  provides  the  user  with  anything  required  at  the 
time  the  user  calls  on  a graphics  routine.  This  ideal  gr£q>hics  device 
provides  a bridge  between  the  actual  output  device  and  the  program. 

The  ideal  graphics  device  uses  what  is  called  a normalized  device 
coordinate  (NE)C).  This  means  that  the  coordinates  on  the  ideal 
graphics  device  are  consistent  Most  ideal  device  systems  have  a 
coordinate  ^tem  where  the  x values  range  between  0 and  1 and  the 
y values  range  between  0 and  1.  This  is  a true  set  of  normalized 
coordinate.  In  practice,  the  actual  range  is  irrelevant  as  long  as  it  is 
consistent  GEM  uses  a range  of  0 to  32,767  for  both  the  x and  y 
coordinates.  The  origin  of  this  system  varies  with  the  implementation 
of  the  ideal  device.  For  GEM  the  origin  coordinate  (0,0)  is  located  in 
the  lower  left  comer.  Another  feature  of  NDC  is  that  the  distance 
between  pixels  is  the  same  in  both  directions.  This  means  that  the 
grid  is  made  up  of  squares  such  as  those  on  graph  paper.  Also,  the 
coordinate  values  increase  from  left  to  right  and  bottom  to  top. 

The  alternative  to  normalized  device  coordinates  is  actual  device 
coordinates — called  raster  coordinates  (RC)  in  GEM.  There  are  several 
differences  between  NDC  and  RC.  First,  the  RC  origin  may  vary.  As 
mentioned  earlier,  most  computer  displays  have  the  origin  in  the 
upper  left  comer.  Another  difference  is  that  the  range  of  coordinate 
v^ues  depends  on  the  resolution  of  the  device.  Also,  the  direction  in 
which  coordinate  values  increase  can  vary.  Finally,  the  distance  be- 
tween pixels  may  not  be  the  same  in  bo^  directions.  The  problem 
with  this  attribute  is  that  a circle  on  one  device  may  appear  as  an 
ellipse  on  another  device.  When  you  work  in  raster  coordinates,  your 
program  becomes  device-specific. 

Idealty,  you  want  your  program  to  remain  as  device-independent  as 
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possible.  Therefore,  you  want  to  use  NDC  for  your  graphic  output 
GEM  allows  you  to  use  NDC  for  your  programs.  Your  program  draws 
its  images  using  NDC,  and  GEM  uses  its  device  drivers  to  output  the 
image  using  the  raster  coordinates.  The  device  driver  takes  into 
consideration  all  of  the  device’s  attributes  such  as  resolution  and 
pixel  distance.  The  device  driver  converts  the  image  so  that  if  you 
draw  a circle  and  output  it  to  a screen,  plotter,  printer,  or  other  ou^ut 
device,  it  looks  like  a circle.  It  heis  the  same  shape  and  size  (relative 
to  the  other  objects  in  the  image)  on  each  device. 


The  GEM  Workstation 


The  workstation  is  GEM’s  Implementation  of  the  ideal  graphics 
device.  It  contains  all  capabilities  of  the  ideal  graphics  device  such  as 
using  NDC.  The  GEM  workstation  contains  a large  number  of  graphic 
attributes  that  you  can  set  These  attributes  tell  GEM  how  objects 
such  as  lines  should  be  drawn.  For  example,  a line  can  be  drawn  solid, 
dotted,  dashed,  dot-dashed,  or  in  some  other  fashion.  Once  you  set 
the  particular  attribute,  you  don’t  need  to  worry  about  it  If  you  want 
to  change  it  simpty  set  it  to  a new  value.  The  graphics  attributes 
provide  you  with  a wide  range  of  tools  to  help  you  create  spectacular 
graphic  Images. 

Other  workstation  attributes  include  fill  settings,  line  settings,  text 
settings,  writing  modes,  and  clipping.  Fill  settings  correspond  to 
commands  that  cause  areas  of  the  screen  to  be  filled,  like  drawing  a 
filled  shape.  Fill  settings  cover  the  color  to  be  used,  type  of  fill  (hollow, 
solid,  pattern,  hatch,  or  user-defined),  and  pattern  or  hatch  selection. 
Line  settings  Include  line  width,  color,  type  (as  mentioned  above),  and 
end  point  stjdes.  Text  settings  include  font  selection,  size,  special 
effects,  color,  and  rotation.  The  writing  modes  (replace,  transparent 
XOR  and  reverse  transparent)  have  alreeidy  been  introduced.  All  of 
these  attributes  are  defined  for  the  worlratation.  Any  VDI  output 
fimction  uses  some  combination  of  these  attributes  when  it  produces 
its  image.  The  current  attribute  setting  may  be  changed  at  any  time. 
Any  output  following  the  change  uses  the  new  attribute  value.  Table 
2-4  shows  the  default  values  for  some  of  the  workstation  attributes. 
All  these  attributes  are  explained  and  demonstrated  in  greater  detail 
in  Chapter  4. 

The  last  attribute  listed  in  Table  2-4,  clipping,  is  actualfy  a function 
done  GEM.  The  program  can  specify  a rectangle  on  the  workstation 
which  outlines  the  area  to  be  visible.  Any  point  a program  tries  to 
draw  outside  of  the  rectangle  is  not  drawn.  Lines  drawn  from  within 
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Table  2-4:  GEM  Woihstation  Attribute  Defonlte 

Attribute D^aidt  Setting 


Character  height 
Character  base  line  rotation 
Text  alignment 
Text  stj^e 
Line  width 
Marker  height 
Poty-llne  end  slides 
Writing  mode 
Input  mode 

Fill  area  perimeter  visibility 

Line  stjde 

Fill  pattern 

Cursor 

Clipping 


Nominal  character  height 
0 degrees  rotation 
Left  base  line 
Normal  Intensity 
Nominal  line  width 
Nominal  marker  height 
Squared 
Replace 

Attempts  to  use  all  types  of  input 

Edges  will  be  drawn 

SoUd 

SoUd 

Hidden 

Disabled 


the  rectangle  to  the  outside  show  only  that  portion  of  the  line  that 
falls  within  the  rectangle.  Clipping  is  also  demonstrated  in  Chapter  4. 

You  now  have  a basic  understanding  of  the  GEM  VDI  and  its 
capabilities.  All  output  for  the  GEM  VDI  is  done  on  a workstation. 
The  next  chapter  develops  the  basic  routines  needed  to  get  an  ap- 
plication running  on  the  Atari  St 


CHAPTER  THREE 


Preparing  to  Use  GEM 


GEM,  as  Its  name  implies,  is  an  environment  manager.  From  the 
programmer's  perspective,  it  provides  the  tools  that  help  produce 
graphics-based  programs.  In  addition  to  the  sophisticated  graphic 
images  that  can  be  produced.  GEM  provides  independence  from 
output  devices  and  portability^  to  many  host  computers. 

All  these  features  do  not  come  fiee.  GEM  places  the  small  but 
Important  restriction  that  you  follow  certain  sequences  of  procedures 
while  your  program  is  executing.  These  procedures  tell  GEM  what 
your  program  wants  done,  how  it  is  to  be  done,  and  what  attributes 
are  to  be  used.  The  most  basic  progrEun  would  perform  the  following 
sequence  of  operations: 

Initialize  the  application  for  GEM; 

Locate  the  physical  Input/output  device  for  the  tystem; 

Obtain  an  Input/output  device  for  the  program; 

Do  the  application's  procedures; 

Release  the  program’s  input/output  device; 

Terminate  the  application  from  GEM. 

Initializing  the  application  for  GEM  performs  two  steps.  First  it 
identifies  the  program  to  GEM,  and  second,  it  allocates  memoiy  for 
the  program  to  use.  Identifying  the  program  to  GEM  allows  GEM  to 
track  input  to  and  output  from  the  program.  GEM  is  designed  to  be 
a multitasking  environment  which  means  that  more  than  one  ap- 
pllcation  may  be  active  at  any  given  tlm&  This  condition  is  best 
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demonstrated  on  the  Atari  ST  by  having  a program  running  (an 
editor,  for  example)  and  accessing  one  of  the  desk  accessories.  When 
you  request  the  desk  accessory,  it  becomes  available  on  the  desktop. 
The  editor  is  still  active  and  you  can  switch  finm  the  accessory  to  the 
editor  and  back  again.  GEM  must  know  which  application— the  editor 
or  the  accessory— is  current^  rurmlng  so  that  when  the  user  provides 
input  GEM  can  direct  the  input  to  the  proper  program. 

When  a program  is  running,  it  needs  memory  to  perform  its 
processing.  The  second  part  of  initialization  tells  GEM  to  allocate 
memory  for  this  program.  If  your  program  does  not  perform  this 
initialization  step,  you  will  vmdoubtedly  interfere  with  GEM's  opera- 
tion. This  can  result  in  Improper  program  execution,  loss  of  a device 
such  as  the  disk  drive  or  mouse,  or  a ^tem  crash  (also  known  as  a 
bomb). 

The  next  two  steps  your  program  must  perform  locate  the  in- 
put/output devices  used  by  the  ^tem  and  your  program.  A true  Atari 
ST  application  causes  all  output  to  be  written  onto  the  program's 
output  device  or  to  a window.  If  you  are  Just  writing  a quick  little 
program  that  uses  only  the  C/UNDC-compatlble  text  output  com- 
mands such  as  prlntn ),  you  won't  need  to  access  these  devices.  You 
also  won't  be  able  to  access  any  of  GEM's  graphic  and  text  output 
capabilities. 

The  system  and  program  input/output  device  is  implemented  using 
the  workstation  concept  introduced  in  Chapter  2.  The  use  of  a 
workstation  and  the  reason  a ^tem  and  program  workstation  is 
required  are  discussed  in  more  detail  in  the  next  section. 

The  next  step  in  your  program  is  for  it  to  do  its  processing.  This 
can  be  an3dhlng  3rau  program  your  application  to  do.  Once  your 
program  has  finished  its  processing,  it  must  return  its  resources  to 
GEM.  The  first  resource  the  program  returns  is  the  workstation. 
Returning  the  workstation  to  GEM  releases  the  memory  allocated  to 
it  and  makes  it  available  to  other  programs. 

The  final  step  is  telling  GEM  that  the  program  Is  reacfy  to  terminate. 
This  allows  GEM  to  get  the  second  resource  used  by  the  program — its 
memory  workspace.  GEM  terminates  the  program  and  returns  its 
memory  to  the  available  pool.  The  program  termination  also  removes 
the  program  from  GEM's  list  of  active  processes  so  that  it  no  longer 
receives  input  from  the  i^tem. 

These  six  steps  provide  the  very  basic  outline  of  a GEM  s^pUcatlon. 
The  next  few  chapters  focus  strictly  on  the  VDI.  This  means  that  the 
programs  do  not  use  menus,  windows,  dialog  boxes,  or  mouse  input 
When  the  AEJS  is  introduced,  a few  more  steps  need  to  be  added.  In 
the  meantime,  the  above  list  of  steps  is  the  basis  for  the  application 
skeleton  developed  in  the  remainder  of  this  chapter. 
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Workstation  Usage 


Chapter  2 introduced  the  concept  of  a workstation.  A workstation  is 
a mechanism  through  which  a program  can  develop  a graphic  output 
environment  The  workstation  keeps  track  of  the  attributes  currently 
being  used  for  graphic  output  However,  this  is  not  the  only  informa- 
tion the  workstation  uses.  The  workstation  also  Identifies  the  location 
of  the  graphic  device,  its  output  capabilities,  its  input  capabilities, 
and  its  physical  attributes.  For  a full  list  of  workstation  data,  see  the 
VDI  functions  v_opnwk( ) and  yq-extn<l( ) in  ^pendlx  A 

When  your  application  begins  Its  execution,  it  requests  from  GEM 
the  workstation  used  by  the  ^tem.  This  workstation  corresponds  to 
the  video  display,  keyboard,  and  mouse  (collective^  known  as  the 
console)  of  the  Atari  ST.  GEM  identifies  the  workstation  by  returning 
a number  called  a handle.  A handle  is  simply  a data  item  (in  this  case, 
a number)  used  to  iiniqu^  identify  some  object  For  example,  the  C 
function  fopenO  returns  a pointer  to  a FILE  object  The  pointer  Is  a 
handle.  The  C function  openO  returns  an  integer  identifier  to  the  file. 
This  int^er  is  also  considered  a handle.  Once  you  know  the  handle  of 
a workstation,  you  always  use  that  handle  when  you  want  to  use  that 
workstation. 

After  you  obtain  the  handle  to  the  ^tem  workstation,  you  need  to 
create  a workstation  for  use  by  your  program.  This  is  done  through 
a process  called  opening  a workstation.  When  your  program  opens  its 
workstation,  you  often  want  to  use  the  screen  and  the  keyboard  as 
weU.  Unfortunately,  GEM  is  alreacfy  using  the  console  for  the  ^tem 
workstation.  Fortunatefy,  GEM  provides  a way  around  this  problem. 

GEM  uses  two  types  of  workstations;  a physical  workstation  amd  a 
virtual  workstation.  A physical  workstation  is  a workstation  attached 
to  a ph}^ical  device  such  as  a console,  printer,  or  plotter.  E)ach  device 
has  a unique  device  identification  number  and  a corresponding 
device  driver  (see  Table  3-1).  The  devices  available  to  the  ^tem,  their 
ID  numbers,  and  their  device  drivers  are  listed  in  a file  called 
ASSIGN.SYS.  This  file  is  read  when  GEM  first  loads  into  the  system. 
Device  drivers  and  alterations  to  the  ASSIGN.SYS  file  are  b^nd  the 
scope  of  this  book.  They  have  been  presented  here  to  clarify  worksta- 
tion usage.  For  further  information,  look  in  a book  that  discusses  the 
implementation  of  GEM  on  a computer.  When  }rou  open  a physical 
workstation,  you  specify  the  physical  device  ID.  GEM  locates  the  device 
and  creates  a workstation  for  it  Only  one  physical  workstation  may 
be  allocated  to  each  physical  device.  As  long  as  the  GEM  desktop  is  in 
use,  it  has  a physical  workstation  open  for  the  console.  You  can  use 
this  physical  workstation  as  jrovu:  program’s  workstation.  However,  if 
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you  change  any  attributes,  these  changes  remain  in  use  when  your 
program  exits  and  GEM  returns  to  the  desktop.  To  use  the  ^tem 
workstation,  your  program  has  to  remember  the  setting  for  each  at- 
tribute and  restore  these  settings  before  exiting  back  to  the  desktop. 
This  is  quite  cumbersome  so  GEM  provides  an  easier  method. 


Table  3-1:  Device  Identification 
Nomber 


Device 

Range  of  ID  Numbers 

Monitor 

1-10 

Plotter 

11-20 

Printer 

21-30 

Metafile 

31-40 

Camera 

41-50 

Tablet 

51-60 

The  virtual  workstation  is  similar  to  the  physical  workstation  in 
appearance.  The  onty  difference  between  the  two  is  that  a virtual 
workstation  is  attached  to  a physical  workstation  instead  of  a physi- 
cal device.  Any  number  of  virtual  workstations  may  be  associated  with 
a physical  workstation.  This  means  that  your  application  can  open  a 
virtual  workstation  attached  to  the  ^tem  workstation,  change  the 
program’s  workstation  as  required,  and  exit  back  to  GEM  without 
affecting  the  desktop’s  workstation  attributes  at  all.  Even  though 
both  workstations  output  to  the  same  screen,  the  program’s  worksta- 
tion defines  an  environment  completely  independent  of  the  ^tem 
workstation’s  environment 

Your  program  can  open  two  or  more  virtual  workstations  to  provide 
for  different  types  of  ou^ut  For  example,  in  a computer-aided  design 
program,  you  use  three  workstations.  The  first  workstation  might  be 
for  grsq>hic  output  and  use  small  letters,  thin  lines,  and  the  color 
black.  Ihe  second  workstation  might  be  for  command  and  status 
output  and  use  larger  letters  and  the  color  blue.  The  third  worksta- 
tion might  be  for  error  messages  and  use  the  color  red  and  perhaps 
a different  font  altogether.  While  j^ur  program  runs,  it  would  choose 
the  appropriate  wortetation  depending  upon  the  type  of  output  being 
produced.  An  example  of  multiple  workstations  is  given  in  Chapter  4. 

When  your  program  has  finished,  it  must  relinquish  its  worksta- 
tions before  it  returns  to  the  desktop.  This  allows  GEM  to  reclaim  the 
memory  used  by  the  workstations  emd  to  make  any  physical  devices 
available  to  other  programs.  For  each  workstation  opened  by  your 
program,  you  must  have  a corre^ondlng  close  workstation  command. 
The  ^tem  workstation  remains  open  because  it  was  opened  by  the 


Preparing  to  Use  GEM  33 


desktop  before  your  program  was  initiated.  If  you  were  to  close  the 
^tem  workstation,  the  desktop  would  not  have  an  output  device  and 
the  ^tem  would  bomb. 


The  GEM  Sk^eton  Program 

As  mentioned  at  the  beginning  of  this  chapter,  use  of  GEM  does  not 
come  without  a price.  Your  first  programming  task  is  to  enter  text 
compile,  and  link  a file  that  performs  all  the  overhead  routines  used 
in  a GEM  explication.  Entering  and  debugging  this  file  at  this  time 
saves  much  time  in  later  programming  exercises  and  in  your  own 
applications.  This  outline  program  file  is  used  for  all  the  program- 
ming exercises  and  can  be  used  as  the  basis  for  any  GEM  program 
you  write. 

Orgcmizing  the  Outline 

In  every  GEM  program  there  is  a minimum  amount  of  overhead.  In 
Chapter  1 the  global  VDI  arrajrs  are  listed.  At  the  beginning  of  this 
chexter,  the  basic  GEM  interfece  procedures  are  listed.  To  make 
programming  somewhat  easier,  several  more  global  variables  are 
added.  All  this  information  In  a program  can  produce  a very  confusing 
source  code  file.  To  avoid  this,  the  outline  program  has  been  divided 
into  six  major  sections:  ^tem  header  files  and  constants.  GEM 
application  overhead,  application-specific  data.  GEM-related  func- 
tions, application  functions,  and  the  main  program. 

When  you  are  writing  a GEM  application,  it  is  extreme^  important 
to  keep  your  program  organized.  Because  all  programs  in  this  book 
use  this  outline  format,  we  suggest  that  you  stick  with  this  format 
for  now.  If  you  decide  on  a different  format  for  your  own  programs, 
try  it  later.  Remember  that  origanization  is  the  kqr.  If  you  don’t 
organize  your  programs,  you  spend  more  time  looking  through  your 
files  than  you  do  programming. 

The  outline  program  referred  to  in  this  section,  called  OUTLINE.C, 
is  shown  In  Listing  3-1. 

Header  FQes 

The  section  titled  “System  Header  Files  & Constants"  lists  the  four 
files  stdio.h,  osbind.h,  gemdefsh,  and  obdefs.h.  These  are  standard 
header  files  for  the  VDI  used  on  most  compilers  and  are  used  in  aU 
programs  in  this  book.  This  section  also  defines  the  constant  values 
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UstingS-l  Piognim  OUTLINE.C 


OUTLINE .C  Dutline  for  GEN  application  C program 
Use  this  out line  to  organize  your  C programs. 


System  Header  flies  & Constants 


ttinclude 

<8tdio.h> 

Standard  10 

It  include 

<osbind.h> 

GEMDDS  routines 

ttinclude 

<gemdefs.h> 

y*  GEM  AES  *y 

It  include 

<obdefs.h> 

y*  GEM  constants 

ttdefine 

FALSE  0 

Udef ine 

TRUE  • FALSE 

/««»«««  «««»»«««»«  ««  «««««»«  «IHH(  ««»«««  « 

GEN  Application  Overhead 

»»»«««»»»«««»««»«»»««««»««««»«««««»»««»«««»«««»«««/ 


Declare  global  arrays  for  VDI. 


typedef 

int  NORD; 

/» 

WORD  is  16  bits  »y 

UORD 

contrl(12). 

/» 

VDI  control  array 

intout [128],  intin[12B), 

/» 

VDI  input  arrays  *y 

ptsin[126],  ptsout[128]; 

✓» 

VDI  output  arrays 

NQRD 

screen^vhandle. 

virtual  screen  uorkstation  ^ 

screen^handle. 

physical  screen  uorkstation 

screerL.rez, 

✓» 

screen  resolution  0,1«  or  2 

color^creen. 

✓» 

flag  if  color  monitor  *y 

>cjnax. 

max  X screen  coord  *y 

y^jnax; 

✓« 

max  y screen  coord 

Application  Specific  Data 


GEM- related  Functions 
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Ll8tliig3-1  (continaed) 

UORO  open.vuorl<(phy8_inandlG) 

UORD  physJiandie; 

Function:  This  function  opens  a virtuai  uorkstation. 

Input:  physJiandie  = physicai  uorkstation  handle 

Output:  Returns  handle  of  uorkstation. 

{ 

UORD  uorl<_ln(ll], 

uorkjout[57] , 

neu-handie;  handle  of  uorkstation 

int  i; 

for  (1=0;  1 < 10;  i++)  set  for  default  values 

uork^in(i]  =1; 

uork^n[10]  =2;  use  raster  coords  *>’ 

neu_handl0  = phys-handle;  use  currently  open  ukstation  *y 

v_opnvuk(uork^n«  &neu_handle,  uork.jDut); 
return ( neu-handle ) ; 

> 

set^creen.^ttr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen^vhandie. 

Output:  Sets  x^ax,  y_max,  coior^creen,  and  screerL-rez. 

< 

UORD  uorkuout[57] ; 

vqusxtnd(screen_vhandie,  0,  uork^ut); 

X— max  = uork^ut[0]; 
y^ax  = uork^ut[l]; 

screerv-rez  = Getrez();  0 = lou,  1 = med,  2 = high  */' 

coior-screen  = (screerurez  < 2);  mono  2,  color  0 or  1 

> 


Rpplication  Functions 


Main  Program 

«»«)(«»»»««»««««««»««»««««««««»««««««««««««««««««««/ 

main( ) 

{ 

int  ap_ad;  application  init  verify  */ 
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UstingS-l  (contliMxed) 

I40R0  gr-tachar,  gr_hchar,  valuss  For  VDI  handle 

gr^box,  grJibox; 

Initialize  GEM  Recess 


ap.id  = appi^nitO; 
if  (ap^d  < 0) 

{ 


Initialize  RES  routines  *y 
no  calls  can  be  made  to  RES 
use  GEMDOS 


Cconws(  Initialization  Error.  <***Nn"); 

Cconus( "Press  any  key  to  continue. Nn" ) ; 

Craucin( ) ; 

exit(-l);  set  exit  value  to  shou  error 


screen_phandie  = Get  handle  for  screen 

graf^andie(&gr_uchar,  &grjichar,  &gr_wbox,  &grJnbox); 
8creea.vhandie  = operL.vuork(8creen_phandie) ; 
8et_screen_attr( ) ; Get  screen  attributes 


Rppiication  Specific  Routines 


Program  Clean-up  and  Exit 


Uait  for  keyboard  before  exiting  program 

CrauclnO;  GEMDOS  character  input 

v-j:i8vul<(scrBen_vhandie) ; close  uorkstation 

appi-exitO;  end  program 


H^UE  and  FALSE.  These  constants  are  defined  for  the  sake  of  con- 
venience and  to  make  your  code  more  readable. 

The  first  header  file  included  in  this  section,  stdio.h,  controls 
standard  input  and  output  It  includes  some  C definitions  for  fime- 
tions,  external  declarations  specifying  function  fypes,  and  some  sys- 
tem constants.  File  stdio.h  may  vaiy  from  compiler  to  compiler.  This 
means  that  you  may  need  to  include  some  other  declarations  to  get 
your  Atari  program  to  run.  If  this  is  the  case,  you  may  add  these 
declarations  to  the  stdlo.h  file  or  you  may  put  them  in  this  section  of 
the  outline  program. 

The  second  header  file,  osbindLh,  declares  the  function  biosO, 
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dtiosO.  and  gemdosO.  which  actually  Interface  with  the  operating 
system.  Additional^.  osbind.h  defines  the  functions  names  for  the 
particular  BIOS.  XBIOS.  and  GEMDOS  calls  using  the  ^define 
precompiler  directive.  For  example,  the  function  8ettime( ) is  actually 
an  XBIOS  call  and  is  defined  as  this: 

#define  Settime(a)  d>io8(22,  a) 

The  function  zbiosf)  calls  XBIOS  routine  number  22  with  the 
parameter  a The  purpose  of  this  ^define  statement  is  to  make  your 
program  more  readable  and  easier  to  write  because  you  don’t  have  to 
remember  what  number  to  use  for  the  set  time  function.  A complete 
listing  of  the  header  files  is  included  in  i^pendix  B. 

The  last  two  heetder  files.  gemdefs.h  and  obdefe.h.  primarlfy  contain 
definitions  for  constant  values  used  by  GEM.  For  example,  some  GEM 
functions  use  one  of  their  parameters  to  define  the  ty^  of  operation 
to  perform.  The  writing  modes  are  a good  example  of  this.  As  ex- 
plained earlier,  the  writing  mode  you  use  can  be  replace,  transparent 
XOR.  or  reverse  transparent  As  a parameter  in  the  set  writing  mode, 
these  modes  have  numerical  values  of  0.  1.  2.  or  3.  respective^. 
Instead  of  having  to  remember  these  values,  you  can  use  the  constant 
names  MD-REPLACE,  MD.TRANS,  BID  JKOR,  and  MD-BRASB.  This 
makes  your  programs  much  easier  to  read,  write,  and  understand. 

GEM  Application  Overhead 

The  second  major  section  of  the  outline  program  contains  informa- 
tion for  GEM’S  application  overhead.  Included  in  this  section  are 
declarations  for  the  variables  used  by  the  VDI  and  some  variables  you 
use  to  describe  the  environment  the  program  is  running  in. 

The  first  line  in  this  section  is  a typedef  operation.  This  line 
defines  a new  variable  type  called  WORD  to  be  equivalent  to  an 
integer.  A type  definition  tells  the  computer  what  kind  of  data  it  is 
processing.  All  GEM  documentation  uses  the  type  WORD  for  data 
processing.  On  the  68000  microprocessor,  the  length  of  a word  is  the 
same  size  as  an  int^er.  that  is,  16  bits.  To  remain  consistent  with 
the  GEM  documentation,  the  type  WORD  is  used  throughout  this 
book  for  all  GEM  parameters.  This  definition  also  allows  for  easy 
portability  of  }rour  programs.  If  you  move  the  program  to  another 
computer  with  a different  word  size,  you  can  simply  redefine  WORD 
and  recompile  the  program. 

The  first  use  of  type  WORD  is  to  declare  the  ^obal  arrays  used  by 
GEM,  which  include  contil[12].  intout(128].  lntin[128].  ptsiii(128]. 
and  ptsoatI128].  These  arrays  are  discussed  in  det^  in  Chapter  1. 

The  next  set  of  lines  under  GEM  ^plication  Overhead  are  declara- 
tions for  variables  used  by  the  programs  in  this  book.  The  first  of 
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these  variables,  screen-vliandle,  is  a handle  to  the  virtual  workstation 
for  the  console.  The  second  variable,  screen-phandle,  is  a handle  to 
the  physical  workstation  of  the  console.  Screen-iez  is  the  resolution 
and  is  either  0,  1,  or  2 (low  resolution,  medium  resolution,  or  high 
resolution,  respectlvety).  Color-screen  is  a flag  that  is  TRUE  If  the 
program  is  running  on  a color  monitor:  otherwise  It  is  FALSE.  jg-mAir 
and  y-maz  are  the  values  of  the  maximum  cooitlinates  in  the  x and 
y directions  on  the  current  screen. 

Application-Specific  Data 

Because  this  is  an  outline  program.  It  does  not  perform  an  applica- 
tion. Therefore,  this  section  does  not  require  any  information. 
However,  when  you  b^in  to  write  applications,  this  section  will  hold 
the  global  variables,  structure  definitions,  and  constant  definitions 
used  specifically  by  your  application. 

GEiM-Related  Functions 

For  now.  this  section  provides  a general-purpose  open  virtual  worksta- 
tion function  and  initialization  function.  Function  open-vwork( ) 
opens  a new  virtual  woiicstation.  Its  input  parameter  is  the  handle  to 
the  ph^ical  workstation  to  which  this  virtual  workstation  is  at- 
tached. Function  open-vwoikO  returns  the  handle  of  the  new  virtual 
workstation. 

Here  is  the  first  use  of  the  VDI  function  v-opnvwk( ).  This  function 
opens  a virtual  workstation  and  has  three  parameters:  an  input  array 
of  eleven  elemente,  the  address  of  the  handle  to  a physical  worksta- 
tion. and  an  ou^ut  array  of  57  elements.  The  input  array  specifies 
the  settings  for  several  of  the  workstation  attributes.  The  last  dement 
specifies  the  coordinate  system  to  use.  The  output  array  contains 
information  about  the  new  workstation  such  as  ptxd  size  and  various 
output  capabilities.  V_opnvwk( ) returns  the  handle  of  the  new  virtual 
workstation  in  place  of  the  physical  workstation  handle.  For  example, 
in  open_vwork( ) In  the  outline  program,  the  input  array  work-in(  ] 
is  set  to  specify  the  default  values  except  for  the  coordinate  ^tem. 
Here  the  raster  coordinates  are  used,  (^len-vwoilcf ) calls  v_<^uvwi^ ) 
with  the  input  eirray,  the  physical  handle  passed  in  phys-handle,  and 
the  output  array.  Open-vwork( ) then  returns  the  value  of  the  new 
handle.  If  the  value  of  the  han<fle  is  0,  the  v-opnwHc( ) function  is 
tmsuccessful. 

All  GEM  and  Atari  functions  are  listed  in  the  appendices  of  this 
book.  For  this  reason,  whenever  a new  GEM  or  Atari  function  is 
introduced,  its  purpose  and  usage  in  the  application  program  is  given 
a detailed  explanation.  However,  details  of  parameters  and  values 
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returned  can  be  fovind  in  the  appendices.  In  most  cases,  such  descrip- 
tions are  useless  as  in  the  case  of  the  y_opnvwk( ) function,  because 
all  default  attributes  can  be  set  using  a clearly  la^Ued  VDI  function 
(see  Chapter  4).  Many  of  the  returned  values  are  of  little  use  for  most 
applications.  Some  of  these  values  are  used  in  the  next  function  listed 
in  program  OUTLINE.C. 

You  may  wonder  why  the  RC  system  is  used  as  a default  for  the 
screen.  This  is  because  the  virtual  workstation  must  inherit  the 
physical  workstation’s  coordinate  system.  The  GEM  desktop  opens 
the  screen’s  physical  workstation  using  raster  coordinates  because 
the  AES  works  with  raster  coordinates.  Therefore,  any  programs  you 
write  that  use  the  ^tem  monitor  or  the  AE^,  must  work  in  raster 
coordinates.  If  you  have  another  monitor  attached  to  your  computer 
with  its  appropriate  device  driver,  you  can  open  a physical  worksta- 
tion for  it  using  NDC.  If  you  tiy  to  open  a virtual  workstation  for  the 
Intern  screen  with  NDC,  GEM  automatically  overrides  your  setting 
and  changes  it  to  RC. 

The  second  function  defined  in  the  section  for  GEM-related  func- 
tions is  called  set_screen_attr( ).  This  function  sets  the  global  vari- 
ables x-max,  7_max,  scxeen-rex,  and  color-screen.  To  obtain  the 
values,  a call  to  VDI  function  vq_exbid( ) is  made.  The  vq_extnd( ) 
function  exemplifies  the  standard  format  for  all  VDI  function 
parameter  lists.  All  VDI  function  parameter  lists  have  as  their  first 
parameter  the  handle  to  a workstation.  The  only  functions  that  vary 
from  this  format  are  v_opnedc( ) and  v_<q>nvwk( ).  As  stated  earlier, 
all  VDI  input  and  output  is  associated  with  a particular  workstation. 
Thus,  any  VDI  function  must  have  a workstation  handle  (either 
physical  or  virtual)  as  its  first  parameter. 

The  vq_extnd( ) function  also  has  a second  and  third  parameter. 
The  second  parameter  determines  the  set  of  attribute  values  to  be 
returned.  If  the  parameter  is  a 0,  the  same  values  returned  by  the 
v-<^nwk( ) function  are  returned.  If  the  parameter  is  a 1,  an  extended 
set  of  values  is  returned.  The  third  parameter  is  an  array  of  57 
elements,  which  holds  the  returned  values. 

In  set_screen-attr( ),  vq_extnd()  is  called  so  that  it  returns  the 
same  values  as  the  v_opnwk( ) fimctlon.  Then  the  appropriate  global 
variables  are  set  These  values  might  have  been  set  in  function 
open_vwork( ) above.  However,  this  would  only  allow  open_vwork( ) 
to  be  used  once  and  only  for  the  screen.  By  moving  the  Initialization 
of  these  global  variables  to  a separate  function,  you  can  use 
open_vwork( ) to  open  as  many  virtual  workstations  as  needed  for 
any  type  of  device. 

The  XBIOS  function  Getrezf ) is  used  to  retrieve  the  current  screen 
resolution.  Because  of  the  way  Atari  designed  the  ST,  low  or  medium 
resolution  implies  a color  monitor  or  at  least  color  representation  in 
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the  bit  map.  High  resolution  is  available  only  with  the  monochrome 
monitor.  Thus,  if  screen_rez  is  0 or  1,  color-screen  is  set  to  TRUE; 
otherwise  it  is  set  to  FALSE. 

AppUcaHon  Function 

Similar  to  the  section  for  eq>pllcatlon-speciflc  data,  this  section  holds 
the  functions  used  in  application  programs.  Because  OUTLINE.C 
performs  no  action,  there  are  no  functions  listed  here. 

The  Main  Program 

All  C programs  must  have  a function  called  mainf ) where  program 
execution  b^ins.  In  the  GEM  programs  presented  throughout  this 
book,  mainf ) is  used  as  the  flow  control  module.  It  executes  the  list 
of  procedures  given  at  the  beginning  of  this  chapter.  Function  mainf ) 
is  divided  into  three  subsections;  GEM  access  initialization,  ap- 
plication-specific routines,  and  program  clean-up  and  exit 


G]E^  Access  Initialization 

Function  mainf ) begins  by  identifying  Itself  to  GEM  through  the  AES 
function  appLJnitf ),  which  initializes  GEM  to  accept  the  ^plication 
as  an  active  process.  The  AES  responds  by  returning  a positive 
integer  value.  If  a negative  value  is  returned,  the  AE^  has  a problem 
initializing  GEM.  In  this  case,  mainf ) reports  the  error  to  the  user 
and  aborts  the  program.  The  GEMDOS  function  Cconwsf ) writes  a 
string  to  the  console.  A GEMDOS  function  is  used  because  the 
program  has  not  been  properly  initialized  and  }rou  do  not  know  if  you 
have  access  to  the  VDI  or  AES.  The  GEMDOS  function  Crawdnf ) 
vralts  for  input  from  the  console.  It  returns  the  keycode  value  pressed 
without  echoing  the  character  to  the  screen.  When  this  function  is 
called,  the  program  simply  pauses  and  waits  for  the  user  to  press 
akQT. 

If  GEM  application  initialization  goes  weU,  mainf)  continues  by 
initializing  the  program’s  global  variables.  First  the  handle  of  the 
console’s  physical  workstation  Is  requested  using  another  AES  func- 
tion, gra£Jiandlef ).  This  function  returns  the  handle  of  the  physical 
workstation.  It  also  sets  its  four  parameters  to  the  width  and  height 
of  the  ^tem  font  character  cell  fin  pixds)  and  the  width  and  height 
of  a box  large  enough  to  hold  a ^tem  font  character  fin  pixds), 
respectively.  Because  the  function  requires  these  addresses  as 
parameters,  they  have  been  induded.  For  most  programs  in  this  book, 
these  values  are  ignored. 

The  last  two  steps  of  GEM  access  initialization  are  to  ^t  a virtual 
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woiicstation  using  open_vwoik( ) (defined  eariler)  and  to  set  the 
remaining  global  values  through  set-screen_attr( ) (also  defined  ear- 
lier). This  completes  the  first  three  steps  a GEM  application  must 
perform. 


i^^Ucatioii-Specific  Routines 

This  section  contains  calls  to  the  application  functions  defined  under 
the  section  for  application-specific  functions.  General^  these  include 
an  initialization  function  and  several  functions  to  process  your 
program. 


Program  Clean-19  and  Exit 

This  section  covers  the  last  two  steps  a program  must  perform.  First, 
function  Crawcln( ) is  called  to  pause  the  program  before  it  exits.  The 
first  few  programs  you  write  display  some  output  on  the  screen  and 
then  exit  If  your  program  doesn't  pause  before  it  exits,  you  do  not 
see  what  was  drawn  because  the  first  thing  the  desktop  does  is  erase 
the  screen  when  the  program  returns  to  the  desktop.  To  give  you  time 
to  see  what  the  program  produced,  a pause  is  placed  here  before  the 
program  ends. 

The  next  function,  v-dsvwkf).  closes  the  virtual  workstation 
opened  earlier.  It  too.  uses  the  workstation  handle  as  its  first  and 
only  parameter.  Note  that  for  each  workstation  you  open,  you  must 
have  a corresponding  close.  You  should  first  close  all  of  your  virtual 
workstations  using  v_dsvwk().  Ihen  close  all  physical  workstations 
you  opened  using  v_cls\^{ ).  Remember  not  to  close  the  desktop’s 
ph3rsical  workstation  or  you  will  have  problems. 

Finally,  function  <9pL.exit()  tells  GEM  that  the  application  has 
terminated.  This  returns  all  program  memory  to  the  available  pool 
and  causes  the  desktop  to  be  restarted. 

This  is  basicalty  the  minimum  programming  you  need  to  run  a 
program  using  GEM  on  the  Atari  ST.  If  you  want  to  write  a quick  C 
program  using  the  standard  input  and  output  you  can  provided  you 
do  not  use  any  GEM  VDI  or  AE^  function  calls.  You  can  use  GEM 
BIOS  or  XBIOS  calls  freely  in  3raur  C programming  and  you  can  use 
any  standard  C functions.  However,  the  screen  may  act  a little  oddly 
because  your  program  does  not  exactfy  match  the  GEM  interface. 

In  reference  to  fimctlon  origin,  note  that  all  VDI  functions  begin 
with  letter  “v.”  All  GEMDOS  and  XBIOS  functions  begin  with  a capital 
letter.  Standard  C fimctlon  and  functions  written  specifically  for  this 
book  all  begin  with  lower-case  letters.  This  should  help  you  identify 
the  origin  of  a function  in  programs  presented  here  or  dsewhere. 

Now.  you  should  enter  this  outline  program,  compile  it  link  it  and 
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run  It  Nothing  hsqppens  except  that  the  program  runs  and  the  screen 
freezes  because  It  Is  waiting  for  you  to  press  something  on  the 
keyboard.  When  you  strike  a k^r,  the  desktop  returns.  Get  the  outline 
program  working  so  that  it  compiles,  links,  and  executes  without  any 
problems. 


Kinetic  Line  Art 


L1NE^.C  (see  Listing  3-2)  Is  an  example  of  programming  using  the 
outline  program.  This  is  a kinetic  line  art  program  that  draws  what 
sq>pears  to  be  a moving  set  of  lines  on  the  screen. 

Listing  3-2  Program  LINES 

✓»»»*»»»»»»*  « mum  » »»»»»»»» 

LINES. C Orau  kinetic  line  art 

This  program  demonstrates  the  use  of  the  polyline  functions  by 
draulng  lines  betueen  two  pairs  of  moving  points  on  the  screen. 


System  Header  files  & Constants 


Ulncluds  <stdio.h> 
{{Include  <osblnd.h> 
{{Include  <gemdefs.h> 
{{Include  <obdefs.h> 


{{define  FPLSE  0 

{{define  TRUE  IFfiLSE 


Standard  10 
/»  GEMDOS  routines 
GEM  fiES 
GEM  constants 


GEM  Ppplication  Overhead 


Declare  global  arrays  for  VDI. 

typedef  Int  UORD; 

UORD  contrl[12), 

lntout[12a],  lntln[128] 
ptsln[128],  ptsout[128] 

UORD  screen_vhandle, 

sc  rearuphand 1 e , 
screen_rGZ, 
color-screen, 
x-max, 
y_max; 


*/ 

y*  UORD  is  IG  bits 
VDI  control  array 
VDI  input  arrays 
VDI  output  arrays 

y*  virtual  screen  workstation 
physical  screen  workstation 
screen  resolution  0,1,  or  2 
y*  flag  if  color  monitor  *y 
y*  max  X screen  coord  *y 
y*  max  y screen  coord  *y 
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Ustiiig3-2  (continned) 

Rpplication  Specific  Data 

ft  ft  »«««««  K^KII^IIX/ 


Constant  v/alues  for  drauing  area 
int  X— louer,  iouest  x v/aiue 

y_ louer,  iouest  y v/aiue 

x_upper,  highest  x value  */ 

y-jjppor;  highest  y value 


/ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 

GEM-reiated  Functions 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft/ 


UORD  open_vuork(phySu^andle) 

UORD  phys-handie; 

/ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 
Function:  This  function  opens  a virtual  workstation. 

Input:  phys-handie  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft/ 

{ 

UORD  work-in [11], 

workout  [57] , 

neu-handie;  handle  of  workstation 

int  i; 

for  (i  = 0;  i < 10;  i++) 
work_in[i]  = 1; 
uork.in[10]  = 2; 

new_handie  = phys-handie;  use  currently  open  wkstation 

v^pnvuk(uorl<.in,  &neu— handle,  worl<^ut) ; 
vuciruk(newJiandie] ; clear  workstation 

return(neuu-handie] ; 

> 


set—screoruattr ( ) 

/ft»ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen.vhandle. 

Output:  Sets  x_max,  y_max,  coior_screen,  and  scraen_raz. 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft^ftftftftftftftft/ 

{ 

UORD  uork-j3ut[57] ; 


vq_jBxtnd(screerL_vhandie,  0,  workout]; 
x^ax  = work.^ut[0]; 
y_max  = uor(<-jout[l] ; 

screen_rez  = Getrez();  0 = low,  1 = med,  2 = high 

coior^creen  = (screen_rez  < 2);  mono  2,  color  0 or  1 


> 
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Lfatjng  3-2  (continued) 

Rpplication  Functions 

long  RndLrng(lou,  hi) 
long  lou),  hi; 

Function;  Generate  a random  number  betueen  lou  and  hi.  Inclusive. 
Input;  lou  = louest  value  In  range. 

hi  = highest  value  In  range. 

Output:  Returns  random  number. 

( 

hl++;  /*  Include  hi  value  In  range 

return(  (Random()  X (hi  - iou))  + lou); 

} 

Inchk ( K , dx , 1 b , ub ) 

Int  x,dx, ib,ub; 

Function:  This  function  tests  uhether  a number  (x)  ulll  be  outside 
a given  range  If  a move  (dx)  Is  added  to  It.  If  the  test  Is 
true,  the  direction  of  movement  Is  reversed. 

Input;  X number  to  test 

dx  delta  to  add  to  x 

lb  louer  bound 

ub  upper  bound 

Output:  Returns  neu  dx  value. 

{ 

if  ( x+dx  <=  lb  I I x+dx  >=  ub  ) 
dx»=-l; 
return(dx) ; 

) 

drauL.frame( ) 

Function;  Drau  a rounded  rectangle  border. 

Input:  None. 

Output;  None. 

«»#«««««««««««««)(»)(«««)(  «««««/ 

{ 

WORD  pts[4];  array  to  hold  corner  vertices 

Set  boundaries  for  border  rectangle  */ 

pts[0]  = x^louer;  Upper  left 

pts[l]  s y_louer; 

pts[2]  = x^pper;  y*  Louer  right 

pts[3)  = y-jupper; 

v_rbox(screen_vhandle,  pts);  Orau  a rounded  box 
return; 


> 
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Li8tliig3>2  (contimted) 

draia.iine8() 

Function:  Do  kinetic  line  art 

Input:  None. 

Output:  None. 

»»»«««« 

{ 

Int  1 Ine^umber , 
k; 

NOPO  pxl,  pyl, 
px2,  py2, 
pdxl,  pdx2, 
pdyl,  pdy2; 

WORD  rxl,  ryl, 
rx2,  ry2, 
rdxl,  rdx2, 
rdyl,  rdy2; 

WORD  pxy[100],  rxy[100];  arrays  to  hold  2 sets  of  25  lines 

do  begin  screen  control  loop 

{ 

v.jclruk(ecreen.vhandle) ; clsar  screen 

draw.-frafnQ() ; draw  border 

Initialize  line  endpoints 

/*  Line  P endpoints 

pxl  = Rnd.rng(  ( long)x_ lower,  (long)x-jupper) ; 
pyl  B RncUrng(  ( long)y^lower,  ( long)y^pper) ; 
px2  = Rnd_rng(  ( long)x.lower,  ( long)x^pper ) ; 
py2  B RncL.rng(  (long)y.lower,  (lcng)y^ppar) ; 
pdxl  = RncL-rng(  -10L,  10L); 
pdyl  = RncL^ng(  -10L,  10L); 
pdx2  = Rnd^ng(  -10L,  10L); 
pdy2  = Rnd^ng(  -10L,  10L); 

rxl  = Rnd-rng(  (long)x_louer,  (long)x-jipper) ; 
ryl  B Rnd.rng(  (long)y_iower,  (long)y_upper) ; 
rx2  = Rnct_rng(  ( long) x— lower,  ( long)x-Jupper) ; 
ry2  = Rnd_rng(  ( long)y_lower,  ( long)y_upper) ; 
rdxl  = RndLrng(  -10L,  10L); 
rdyl  B Rnd_rng(  *10L,  10L); 
rdx2  B RncLj*ng(  -10L,  10L); 
rdy2  = RndL_rng(  -10L,  10L); 

Each  point  requires  4 elements  In  the  pxy  or  rxy  array.  The  current 
line  drawn  Is  held  In  elements  96,  97,  90,  and  99  for  the  x and  y 
coordinates  of  the  first  endpoint  and  the  x and  y coordinates  of 
the  second  endpoint,  respect Iv/ely.  The  next  line  to  be  erased  Is 
In  elements  0,  1,  2,  and  3. 


loop  control 


endpoint  1 for  line  p 
endpoint  2 for  line  p 
delta  X for  endpoints 
y*  delta  y for  endpoints  *y 


y*  variables  for  line  r *y 
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Ustiiig3-2  (continued) 

for(  ks0;  k<100;  k^-t-  ) 

pxy{k]  = rxy[k]  =0;  clear  arrays 

val_color(8creen-whandle,l) ; Set  color  to  black 
/*  Line  drawing  loop  begins  here 

/*  Change  loop  end  value  to  draw  any  number  of  lines 
do 
< 

rxy[96]  = rxl;  rxy[97]  = ryl;  Set  next  line  to 

rxy[9B]  = rx2;  rxy(99]  = ry2;  be  drawn 

pxy[96J  = pxl;  pxy[97J  = pyl; 
pxy(90J  = px2;  pxy[S9J  = py2; 

v-pllnQ(screerL.vhandle«  2,  &pxyd-96);  Draw  polyline  using 

v^line(screen_vhandle,  2,  &rxy+96);  2 vertices  (one  line) 

v-pline(8creen_vhandie,  2,  &pxy);  Redraw  first  line 

v_plinB(8creen_vhandle«  2,  &rxy);  to  erase  It 

for(  k=0;  k<96;  k++)  Shift  endpoints  in  arrays  */ 

< 

pxy{k]  = pxy(k+4]; 
rxy[k]  = rxy[k+4]; 

> 

Calculate  endpoints  of  next  lines 
pxl  pdxl;  pyl  pdyl; 
px2  pdx2;  py2  4-s  pdy2; 
rxl  +=  rdxl;  ryl  +=  rdyl; 
rx2  +=  rdx2;  ry2  +=  rdy2; 
rdxl  = inchk(rxl,  rdxl,  x^lower,  x_upper); 
rdx2  - lnchk(rx2«  rdx2,  x^ower,  x-ojpper); 
rdyl  = lnchk(ryl,  rdyl,  y^ower,  y-upper); 
rdy2  « inchk(ry2,  rdy2,  y—lower,  y. .upper); 
pdxl  = inchk(pxl,  pdxl,  x^lower,  x.jupper); 
pdx2  = inchk(px2,  pdx2,  x^ouer,  x^pper); 
pdyl  s inchk(pyl,  pdyl,  y_J.ower,  y^pper); 
pdy2  s lnchk(py2,  pdy2,  grower,  y .upper) ; 

) while  (fCconlsO);  check  If  key  pressed 

) while  ((CrawclnO  & 0x7F)  !=  27);  escape  key  exits 

return; 

> 

Main  Program 

maln( ) 

< 

Int  ap_ld;  application  Inlt  verify 

WDRO  gr.jwchar,  gr_hchar,  /*  values  for  VDI  handle 

gr.j«ibox,  gr^box; 
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Llstliig3>2  (continued) 

Initialize  GEM  Recess 

ap^d  = appl-lnltn:  Initialize  RES  routines 

if  (ap-J,d  < 0)  no  calls  can  be  made  to  RES 

( use  GEMDOS 

Cconws(“***>  Initialization  Error.  <»»*Nn*); 

Cconws( 'Press  any  key  to  continue.^n" ); 

Craucin( ) ; 

exit(-l);  sot  exit  value  to  show  error 

> 

8creen_43handle  = Get  handle  for  screen 

graf J^andie(&gr^char,  &gr_hchar,  &gr^box,  &grJibox); 
8creen_vhandie  = operuvuork(screerL4]handie) ; 
set^creerLjattr( ) ; Get  screen  attributes 

Rppiication  Specific  Routines 

vsi.typa(screerL.vhandie,  1);  Set  polyline  pattern  to  solid 

vsi^idth(screen..vhandis,  1);  Set  line  width 

v8f^olor(8cro8n»vhandlo,  0);  Set  fill  color  to  0 (white) 
V8f^eriffleter(8creen.vhandie,  TRUE);  /»  Turn  on  perimeter 
v8ur^ode(8creen.vhandie,  I1D_X0R); 
set  boundaries 
x^ower  = 10; 
y_iower  = 10; 
x-jupper  = x-jnax  - 10; 
y^iipper  = y_max  - 10; 
start  program 

drau^inesO;  Do  line  art 

Program  Clean-up  and  Exit 

««««««»««»««««««««««»»»««»»««««»«««««««««««««««««««/ 

v.xi8vuk(8crBeruvhandie);  y*  close  workstation  *y 

appi^xitO;  y*  end  program 

> 


E^ch  line  consists  of  two  endpoints.  E^ch  endpoint  has  an  x and 
a y coordinate.  To  make  kinetic  line  art.  the  program  draws  a line 
between  the  two  endpoints  and  then  moves  the  two  endpoints. 
Another  line  is  drawn  and  the  endpoints  are  moved  again.  Then 
another  line  is  drawn  and  another  moved.  After  a specified  number 
of  lines  are  drawn  (in  the  case  of  this  program.  25).  the  first  line  is 
erased  before  another  line  is  drawn.  Then  another  line  is  erased  and 
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another  line  drawn.  This  process  continues  until  the  user  presses  the 
Escape  key. 

The  Important  aspects  to  look  for  In  this  program  are  Its  organiza- 
tion and  the  use  of  the  writing  mode  XOR  The  program  builds  on 
the  OUTLINE.C  file  following  Its  Intended  flow  quite  carefiilfy.  The  use 
of  the  XOR  writing  mode  Is  used  In  many  programs  throughout  this 
book. 

As  an  example  of  the  efficiency  of  using  the  XOR  writing  mode, 
assume  that  you  have  a blank  monochrome  screen  where  all  bits  are 
0.  Now,  by  drawing  a line,  you  are  writing  1 bits  onto  0 bits.  Under 
the  XOR  operator,  this  results  in  a 1 bit  at  each  location  under  the 
line  In  the  bit  map.  Therefore,  a line  is  displayed  on  the  screen.  Now 
draw  another  line  directly  on  top  of  the  first  line.  Each  1 bit  on  the 
line  Is  XORed  with  the  1 bit  in  the  bit  map.  At  each  location  in  the 
bit  map,  a 0 results.  The  end  result  Is  that  you  have  erased  the  first 
line.  By  drawing  a line  on  a blank  screen,  you  get  a line  to  appear.  By 
drawing  the  same  line  In  the  same  place,  you  get  the  line  to  disappear. 
This  is  the  unique  feature  of  the  XOR  operaton  If  you  eq>ply  the  same 
XOR  operation  twice  in  a row,  you  wind  up  where  you  started. 

This  fact  about  the  XOR  writing  mode  is  used  In  program  LINES. 
The  program  simply  stores  the  endpoints  for  the  25  lines  shovm  on 
the  screen.  Before  the  next  line  Is  drawn,  the  first  line  Is  redrawn  to 
erase  It  Then  the  next  line  Is  drawn  and  erased  before  a new  line  Is 
drawn.  This  process  can  go  on  and  on.  The  application-specific  data  of 
Listing  3-2  holds  four  variables:  z_lower,  y_lower,  x-opper,  and 
y-vqtper.  Tlie  variables  hold  the  lowest  and  highest  x and  y coordinate 
values  that  can  be  used.  These  values  set  the  range  over  which  the 
lines  can  travel. 

Function  mainf)  gives  an  overview  of  the  program’s  flow.  As  ex- 
pected, the  first  thing  the  program  does  Is  Initialize  GEM  access.  After 
this  Is  done,  the  application  begins  Its  processing. 

Under  the  application-specific  routines,  the  first  five  lines  set  the 
workstation  attributes  to  be  used  the  program.  The  first  function. 
v8L_type().  sets  the  line  pattern  to  be  a continuous  or  solid  line. 
Function  v8L_widt]i( ) sets  the  line  width  to  1 unit  (in  this  case  a 
pixel).  The  VBf-color( ) function  sets  the  fill  color  to  the  background 
color  (white).  The  fill  color  is  the  color  used  when  a pofygon  Is  filled. 
The  next  function.  vsf_perimeter( ).  teUs  the  VDI  to  draw  a perimeter 
when  It  draws  a predefined  shape.  Tlie  last  attribute  function. 
v8wr_mode(),  sets  the  writing  mode  to  XOR  Note  the  use  of  the 
defined  constant  MD-XOR  from  the  osblnd.h  file.  Do  not  wony  about 
fully  understanding  how  these  attribute  functions  work.  The  program 
In  Chapter  4 fulfy  uses  the  workstation  output  and  attributes. 

The  next  step  after  getting  the  workstation  attributes  is  setting  the 
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boundaries  of  the  line-drawing  routine.  The  progreun  arbitrarily 
defines  the  boundaries  to  fall  within  10  pbcels  from  each  edge.  Since 
the  lowest  coordinate  value  Is  alreai^  known  to  be  0.  the  program 
sets  x-lower  and  y_lower  to  the  value  10.  Because  the  upper  coor- 
dinate valu^  are  not  known  imtil  the  program  is  running,  the 
program  uses  the  globed  values  from  x-max  and  y-max  to  determine 
the  upper  limits.  These  values  depend  on  the  type  of  monitor  and 
resolution  used.  Once  the  boundary  values  have  been  set  the  program 
begins  by  calling  function  diawJinesf ). 

Function  diaw-llneaf ) returns  when  the  E^scape  key  has  been 
pressed.  Because  the  user  has  requested  the  program  exit  It  Is  safe 
to  assume  that  the  Images  have  been  drawn  on  the  screen.  Therefore, 
the  Crawciiif ) pause  has  been  removed  from  this  program  and  nor- 
mal program  exiting  is  performed. 

Function  diaw-Unesf ) controls  the  program  flow  while  lines  are 
being  drawn  on  the  screen.  The  program  listed  here  actualty  keeps 
track  of  two  sets  of  lines  moving  Independently  on  the  screen.  TTie 
flow  of  draw-linesf ) follows  this  outline: 

do  begin  the  line  drawing  function 
clear  the  screen 
draw  a border 

randomty  select  the  endpoints  for  lines  P and  R 
random^  select  the  movement  for  each  endpoint 
dear  the  storage  arrays  for  each  set  of  lines 
set  the  line  drawing  color  to  black 
do  begin  the  line  drawing  output 
save  the  next  lines  to  be  drawn  in  the  storage  arrays 
draw  lines  P and  R 

redraw  the  first  lines  In  the  storage  arrays  for  P and  R 
move  each  endpoint 
until  a kQT  Is  pressed 

until  the  k^  pressed  is  the  E^scape  key 

Starting  at  the  top  of  this  outline,  the  entire  draw_Unes( ) function 
is  one  do-whlle  loop,  which  Iterates  each  time  a key  Is  pressed.  If  the 
key  Is  not  the  E^scape  key.  the  loop  repeats.  Thus,  by  pressing  any  key 
other  than  the  E^scape  key.  the  user  can  dear  the  screen  and  start 
the  line-drawing  sequence  over  again. 

The  remainder  of  draw-Unesf ) consists  of  line-drawing  Initializa- 
tion and  a line-drawing  loop.  The  Initialization  process  begins  by 
dealing  the  screen  using  the  v-clndtf ) function.  A border  is  drawn 
by  the  application  function  diaw_£rame( ).  Looking  at  draw_firame( ), 
you  see  an  array  being  Initialized  and  the  VDI  function  v-xbox(). 
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When  drawing  a rectangle,  you  onfy  need  to  specify  the  coordinates 
of  the  upper  left  comer  and  lower  right  comer.  This  is  done  in  array 
pts[  ].  As  discussed  in  Chapter  1,  pts[  ] follows  the  point  array  format 
where  the  first  x coordinate  is  placed  in  element  0 followed  by  its 
corresponding  y coordinate  in  element  1.  The  next  point’s  x and  y 
coordinates  are  stored  in  elements  2 and  3,  respectivefy.  The  function 
v_xbox( ) draws  a filled  rectangle  with  rounded  comers. 

Back  in  draw-lines  ( ) after  the  call  to  dxaw_frame( ).  the  next  step 
is  to  initialize  the  endpoints  of  the  two  lines  and  each  endpoint's 
movement.  The  initial  values  are  chosen  through  the  application 
function  Rnd_mg( ).  Function  Rnd_mg( ) is  the  first  function  defined 
in  the  application  function  section  of  program  LINES.  This  function 
returns  a long  integer  value  within  the  range  specified  by  parameter 
low  and  hi.  The  range  includes  the  values  low  and  hi.  Rnd.ziig( ) uses 
the  XBIOS  function  Randomf ).  Function  Randomf ) returns  a 24-bit 
random  value.  Function  Rnd-cngf ) takes  this  value  and  performs  a 
modulo  operation  to  get  a value  between  0 and  the  difference  between 
hi  and  low.  By  adding  the  value  low  to  the  modulo  result,  Rnd_mg( ) 
produces  a random  number  within  the  range  requested.  The  XBIOS 
function  Randomf ) is  different  from  the  C function  rand( ) in  that 
you  caimot  set  the  seed  for  Randomf ) to  specify  a sequence. 

Once  draw_lines( ) has  set  the  initial  values  for  the  endpoints  and 
their  movement  it  clears  the  arrays  that  keep  track  of  the  lines  on 
the  screen.  Each  line  requires  two  endpoints  and  each  endpoint  uses 
two  values.  Thus,  one  line  is  defined  by  four  elements  in  the  array. 
To  store  25  different  lines,  100  elements  are  required  for  each  array. 
After  clearing  the  arrays,  the  line  color  is  set  and  the  line-drawing 
loop  begins. 

The  VDI  function  to  draw  a line,  v_pline( ),  is  actually  a poljdlne- 
drawlng  routine.  Given  a set  of  points,  v-pUnef ) draws  a line  from 
the  first  point  to  the  second  point  to  the  third  point  and  so  on  until 
the  number  of  specified  points  has  been  reached.  The  points  are 
passed  to  v_pline( ) in  an  array  using  the  standard  VDI  point  format 
For  this  program,  only  two  points  are  specified  because  only  one  line 
is  being  drawn  at  a time. 

The  next  line  to  be  drawn  is  stored  in  elements  96,  97,  98,  and  99 
of  the  line  storage  arrays.  Using  the  fact  that  the  array  name  is  the 
base  address  of  the  array,  the  v_pline( ) function  calls  in  dxaw_llne( ) 
pass  the  address  of  the  96th  element  in  the  array.  Thus,  the  newest 
lines  P and  R are  drawn. 

The  oldest  line  showing  on  the  screen  is  stored  in  elements  0,  1,  2, 
and  3.  By  passing  the  base  address  of  the  array  to  v_pUne( ),  the 
program  redraws  the  oldest  lines  on  the  screen.  By  redrawing  these 
lines  In  the  XOR  writing  mode,  the  program  effectively  erases  the 


Preparing  to  Use  GEM  51 


oldest  lines.  Note  that  until  25  lines  are  drawn,  the  values  In  elements 
0, 1, 2.  and  3 are  all  0.  Therefore,  when  v-plinef ) tries  to  draw  a line 
from  (0,0)  to  (0,0)  it  simply  draws  a point  (a  line  with  no  length)  at 
coordinate  (0,0). 

The  next  step  for  diawJlneO  Is  to  shift  the  position  of  the 
endpoints  In  the  arrays.  Because  each  line  takes  four  points,  each 
point  must  be  shifted  down  by  four  elements.  This  is  done  in  the 
for-loop  shown  in  the  listing. 

The  final  step  for  dfaw-line()  is  to  calculate  the  endpoints  for  the 
next  pair  of  lines.  This  is  done  by  adding  the  appropriate  movement 
value  to  each  coordinate  value.  After  the  movement  values  are  added, 
the  coordinate  values  are  checked  using  application  function  lnchk( ). 
Function  inchk()  tests  if  the  next  addition  of  the  movement  value 
causes  the  coordinate  to  move  bqrond  the  specified  range.  Function 
InchkO  is  passed  the  current  coordinate,  the  current  movement 
value,  the  lowest  range  value,  and  the  highest  range  value.  If  the  next 
coordinate  value  remains  within  the  range,  the  inchk( ) returns  the 
current  movement  value.  If  the  next  coordinate  value  exceeds  one  of 
the  range  limits,  inc]ik( ) returns  the  negative  movement  value.  This 
makes  it  appear  that  the  endpoints  are  “bouncing  off’  the  walls  of 
the  border.  For  example,  suppose  the  x coordinate  limits  are  10  and 
630  (as  on  a monochrome  monitor).  If  pal  has  the  value  of  150  and 
pdzl  has  the  value  of  —4,  the  next  value  of  pal  is  144,  which  is  within 
the  range,  so  inchkf ) returns  the  value  of  —4.  If  pal  has  the  value  of 
12,  the  next  value  of  pod  is  8,  which  is  too  low.  In  this  case,  indik( ) 
returns  4,  so  that  the  next  time  pal  is  changed,  it  is  changed  by  4 
instead  of  —4. 

The  end  of  the  inside  do-while  loop  uses  the  GEMDOS  function 
Cconisf ) to  test  if  the  console  has  a character  waiting  to  be  read  (that 
is,  the  user  has  pressed  a k^).  If  the  function  returns  FALSE,  no  kQr 
has  been  pressed  and  another  line  is  drawn.  If  the  function  returns 
TRUE,  the  user  has  pressed  a k^r  and  the  inner  loop  exits. 

The  outer  do-while  loop  checks  which  key  has  been  pressed  by 
using  the  value  returned  from  function  Crowcin( ).  Function  Craw- 
ciii( ) reads  the  current  character  waiting  to  be  read  from  the  console 
and  returns  the  corresponding  kq^code.  The  k^ode  on  the  Atari  ST 
consists  of  a 16-bit  value.  For  ASCII  characters  (the  first  128  charac- 
ters), the  lower  7 bits  contain  the  ASCII  value.  By  performing  a 
bit-wise  AND  operation  on  the  value  returned  from  CtawdnO,  the 
program  gets  the  ^CII  value  of  the  k^  pressed.  Since  the  ASCII  value 
of  Escape  is  27,  the  loop  begins  again  if  the  value  returned  is  not  27.  If 
Escape  is  pressed,  the  function  dfaw-linesf ) exits  and  returns  to 
main( ).  A listing  of  the  full  keycodes  is  given  in  ^pendix  C. 

This  completes  the  description  of  program  LINES.  Enter  and  com- 
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pile  this  program  to  practice  using  the  OUTLINE  program  and  to  get  a 
feel  for  programming  in  GEM.  When  you  have  LINES  running,  make 
some  changes  to  it  First  tiy  changing  some  of  the  range  values  for  the 
endpoint  initialization.  Then  try  using  the  replace  writing  mode  in- 
stead of  the  XOR  writing  mode.  To  do  this,  draw  the  new  line  using 
line  color  1 (black)  and  the  old  line  using  line  color  0 (backgroimd). 
This  means  that  you  need  to  use  vsl-color( ) to  set  the  line-drawing 
color  before  each  v-pUne( ) call. 


CHAPTER  FOUR 

VDI  Output 
and  Friends 


All  VDI  functions  produce  output  on  a workstation.  A workstation  has 
a logical  bit  map  on  which  all  output  is  product.  Whether  or  not  a 
physical  bit  map  is  used  is  irrelevant,  since  the  output  is  always  the 
same  no  matter  which  device  is  used  to  produce  the  picture.  That’s 
the  principle  behind  using  VDI. 

The  general  procedure  used  in  a GEM  program  is  to  open  a 
workstation  (either  physical  or  virtual)  and  output  the  graphic  draw- 
ings to  it  All  VDI  functions  (Including  input  output  and  workstation 
attributes)  use  a workstation  handle  as  their  first  parameter. 


The  Workstation  Workout 


How  do  you  go  about  using  all  these  functions?  Program  GRAFDEMO 
exercises  the  various  functions  used  to  produce  output  and  set  the 
workstation  attributes.  Go  directly  to  function  main()  in  Listing  4-1 
to  see  the  general  flow  of  the  GRAFDEMO  program.  The  prellmlnaiy 
setup  is  the  same  as  in  the  two  previous  programs,  OUTLINE  and 
LINES.  First  a virtual  workstation  is  opened,  and  then  the  ^obal 
^tem  variables  are  set 

There  are  four  primary  application  functions  used  to  demonstrate 
the  \^urious  workstation  attributes:  draw-Une(),  draw_rect(), 
draw-dxcf ),  and  dcaw_text( ).  Each  works  with  a Afferent  type  of 
output  Function  drawJineO  demonstrates  ^^ous  line-drawing 
capabilities  and  routines  and  attributes  related  to  drawing  lines.  The 
function  draw.jrect( ) demonstrates  drawing  rectangles  and  their  as- 
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Listing  4-1  Program  GRAFDEMO 

GRRFDEMO.C  Demonstrate  VDI  graphics  routines. 


VDI  graphics  routines  are  explained  in  the  text.  Change  this 
program  to  test  different  combinations  of  graphic  attribute 
settings. 

System  Header  Files  & Constants 


Standard  10 
6EKD0S  routines  *>' 
GEM  RES  */ 

GEM  constants 

ltdefine  FRLSE  0 

ttdefine  TRUE  IFRLSE 


ttinciude 

<stdlo.h> 

/» 

ttinclude 

<osbind.h> 

/* 

^include 

<gemdsfs.h> 

^include 

<obdefs.h> 

GEM  Rppiication  Overhead 


/*  Declare  global  arrays  for  VDI. 

typedef  int  I40RD; 

UORD  contri[12], 

intout[128],  lntin[120] 
ptsin[126],  ptsout[120] 

I4DRD  scraerL_vhandie, 

screeruphandie, 
screen_rez, 
coior^creen, 
x^ax, 
y_max; 


*/ 

WORD  is  16  bits 
VDI  control  array 
VDI  input  arrays 
/*  VDI  output  arrays 

virtual  screen  uorkstation 
physical  screen  uorkstation  */ 
/»  screen  resolution  0,1,  or  2 
flag  if  color  monitor 
max  X screen  coord 
max  y screen  coord 


Rppiication-Specific  Data 

GEM- re la ted  Functions 

WORD  opsrL-.vuork(phy8-handie) 

WORD  physJiandie; 

Function:  This  function  opens  a virtual  uorkstation. 
Input:  phys-handle  = physical  uorkstation  handle 

Output:  Returns  handle  of  uorkstation. 


VDI  Output  and  FHends  55 


Listing  4-1  (continued) 

< 

UORD  uorl<-ln[ll], 

uiork_aut[57] , 

neuL-handle;  handle  of  workstation 

Int  i; 

for  (1  = 0;  1 < 10;  i++)  set  for  default  values 

work«ln(i)  = 1; 

work_in[10]  = 2;  use  raster  coords 

neuLJiandle  = phys_handle;  use  currently  open  ukstatlon 

v^pnvuk(uork_ln,  &neuJiandle,  uork_jout) ; 
return(neu_handle) ; 

) 

set^creen-jattr( ) 

Function:  Set  global  values  about  screen. 

Input;  None.  Uses  screenu.vhandle. 

Output;  Sets  x.jnax,  y.jnax,  color_screen,  and  screen^ez. 

< 

UORD  uork^ut[57]; 

vq^xtnd(screen.vhandle,  0,  uork_out); 

x. jnax  = workout  [0]; 

y. jnax  = uork_jDut[l] ; 

screerurez  = Getrez();  ✓it  0 = low,  1 = med,  2 = high 

color^creen  = (screen— rez  < 2] ; mono  2,  color  0 or  1 

) 


Application  Functions 

»»»»»»»»*  It**  »»✓ 

calc-shape(nun)— pts,  a) 

UORD  itnum_pts,  a[]; 

/*****************************************«******** 
Function:  Used  by  draw. llne()  to  calculate  an  arrow  given 
the  leftmost  vertex. 

Input:  = x-coord  of  point. 

a[l]  = y-coord  of  point. 

Output:  Returns  array  a filled  with  points  for  v_pllne 

function  to  draw  an  arrow  with  six  line  segments. 
Num— pts  contains  the  number  of  points  In  the  shape. 
*************************************************** 

< 

✓*  SHfiPEJSIZE  determines  the  size  of  the  arrow 
ttdefino  SHflPEL_SlZE  IB 

*num_pts  = 7; 
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Listing  4>1  (continued) 

«'»  The  arrou  Is  draw  from  the  upper  leftmost  point. 
a(2)  = a[0]  + SHfiPE_SI2E; 
a(3)  = a(l]; 
a(4)  = a(2]; 

a(S)  = a(3]  - SHRPE_SIZE; 
a[6]  = a[2)  + SHRPE_SI2E; 
a(7]  = a(l]  ♦ (SHRPE_5I2E/2); 
a(12)  = a(0]; 

a(13)  = a(l]  4-  SHRPEJSI2E; 
a(10]  = a[2); 
a(ll)  = a(13); 
a(0)  = a(4]; 

a(9]  = a(ll]  ♦ SHRPE_SI2E; 
return; 

> 


drau— line( ) 

Function:  Demonstrate  VDI  line  draulng  functions. 

Input:  Nona. 

Output:  None. 

{ 

UORD  count,  pxg[32]; 

WORD  x[16],  ^[16];  start  points  for  shapes 

int  i; 


x[l]  = 10; 

y(l)  = 20; 

/» 

set 

start  points  1st 

ina 

x[2]  = 70; 

y(2]  = 20; 

x[3]  = 130; 

y(3]  = 20; 

x[4]  = 190; 

y[4)  = 20; 

x[5]  = 10; 

y(S)  = 85; 

set 

start  points  2nd 

line 

x[6]  s 70; 

y(G)  = 85; 

x[7]  = 130; 

y(7)  = 85; 

x[0)  = 190; 

y(8)  = 85; 

x(9)  = 10; 

y(9)  = 150; 

set 

start  points  3rd 

iine 

x[10]  s 70; 

y[10]  s 150; 

x[ll]  = 130; 

y(ll]  = 150; 

x[12]  = 190; 

y(12)  = 150; 

y*  Show  change  in  iina  width 

v-clruk(screerL.vhandla) ; ciear  screen 

for  (i  = 1;  i <=  12;  i++) 

< 

pxy[0]  = x[i];  set  start  points 

pxy(ll  = y(i); 

caic.jBhape(&count,  pxy);  set  arrow 
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Ustiiig  4-1  (contiiitted) 

v8i-i«jldth(8creBri.vhandie,  1);  set  line  width 

v/^llne[8creeiu/handle,  count,  pxy);  draw  line 

> 

CraucinO; 

Show  change  in  line  type 

v^iruk(8creen_uhandie) ; clear  screen 

v8l^idth(screenu.uhandie,  1);  set  default  width 
for  (1  = 1;  1 <=  12;  1++) 

< 

pxy[0]  = x[i];  set  start  points 

pxytl]  = y[l]; 

cai&jshape(&count,  pxy);  set  arrow 

vsl<_type(8creen.uhandie,  i);  set  line  type 

valine (8creert.vhandie,  count,  pxy);  draw  line 

> 

Craucin( ) ; 

Show  change  in  line  end  style 

u^iruk(8creen-.uhandie) ; clear  screen 

U8l^idth(screeruvhandie,  3);  set  medium  width 

pxy[0]  = 50;  pxy[l]  » 20;  draw  squared  ends 

pxy(2]  = 150;  pxy[3]  = 20; 
v/6i^nd8(screerL.vhandie,  0,  0); 
v/^iine(8creen.vhandie,  2,  pxy); 

pxy[0]  s 50;  pxy(l]  =60;  draw  arrow  ends 

pxy [2]  = 150;  pxy(3]  = 60; 
vsi^nds(8creeruuhandie,  1,  1); 
v_piine(8creen^vhandle,  2,  pxy); 

pxy[0]  =50;  pxy[l]  = 100;  draw  rounded  ends 

pxy[2]  = 150;  pxy[3]  = 100; 
v/el_end8(screerL.vhandle,  2,  2); 
u^line(screen_vhandie,  2,  pxy); 

CraucinO; 

Show  change  in  marker  type 

u^lruk(8creerL.vhandle) ; /»  clear  screen  */ 

for  (1  = 1;  i <=  12;  1++) 

< 

pxy[0]  = xflj; 
pxytl)  = yti); 
caic^hap0(&count,  pxy); 
v/8m_type(screerL.vhandie,  i ) ; 
v/^marker(8creeni.uhandie,  count,  pxy); 

> 

Crawcin( ) ; 
return; 

> 
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Listing  4-1  (continned) 

drau^oxes( ) 

Function:  Draus  rectangles  used  VO I routines. 

Input:  None. 

Output:  None. 

< 

I40RD  pxy[4] ; 

u^iruk(screen^vhandie) ; 
vsf-porlmater(screBn»vhandle,  FALSE) ; 
pxy[l]  = 30;  pxy[3)  = 90; 

pxy(0]  = 30;  pxy[2]  = 60; 

vr^ecfi(6creerL_vhandle«  pxy); 
pxy[0]  +=  50;  pxy[2]  +=  50; 
u^box(screen.uhandle,  pxy); 
pxy[0]  +=  50;  pxy[2]  +=  50; 
v-x  f box  ( sc  roerL-vhand  1 e , pxy ) ; 
pxy[0]  +=  50;  pxy[2]  +=  50; 
uJ3ar(screen_vhandie,  pxy); 

v;sf_43arimBter(screen>«vhandlB,  TRUE); 
pxy[l]  = 130;  pxy[3]  = 190; 
pxy[0]  = 30;  pxy(2)  = 60; 
vr^0cfl(screerL-v;handl8,  pxy); 
pxy[0]  'I'S  50;  pxy[2]  +=  50; 
u^box  ( scr een.vhandi  e , pxy ) ; 
pxy[0]  43  50;  pxy[2]  4s  50; 
u^fbox(scre8a.uhandie,  pxy); 
pxy[0]  +=  50;  pxy[2]  +=  50; 
u^ar(scr0en^uhandle,  pxy); 

return; 

> 

draw«r0ct( ) 

Function:  Demonstrate  VDI  rectangle  & area  functions. 
Input:  None. 

Output:  None. 

{ 

UORD  pxy [32]; 
int  i; 


This  first  dravL±axes( ) call  uses  the  attribute  ualues 
* previously  set  by  drau_iina(). 

«✓ 

drau^oxesO ; 

Craucin( ) ; 
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Ustliig4-1  (continued) 

Reset  to  default  values 

vsl^idth(screen-.vhandle,  1);  set  default  width 

vsluends(screen_vhandle,  0,  0];  set  squared  ends 

vsl_type(screen_vhandle,  1);  set  solid  lines 

drauuboxes( ) ; 

Craucln(); 

Fill  attribute  settings 

vsf— In ter lor ( screen— vhandle,  0);  hollow  (default) 

i drawJ30xes( ); 

I CrawclnO; 

L 

^ vsf_lnterlor(screen_vhandle,  1);  solid 

drauu-boxes( ) ; 

CrawclnO; 

vsf— lnterior(screon_vhandle,  2);  use  patterns 

draw-boxes ( ) ; 

Craucln( ) ; 

vef— Inter lor (screen-vhandle,  3);  use  hatches 

drauJboxee( ); 

Crawcln( ) ; 

Display  patterns 

i v^l  rul<(  sc  reen— vhandle) ; 

I vsf— lnterlor(scre0n_vhandle,  2); 

; for  (1  = 0;  l < 32;  1++) 

I < 

I V8f_style(8creen_whandle,  i+1); 

i pxy(0]  = ( (l»8)  » 30)  + 20; 

! pxy(l)  = ( (1^8)  » 30)  + 20; 

i pxy(2)  = pxy(0)  ♦ 20; 

; pxy(3)  = pxy[l]  + 20; 

i vr_recfl(scr8en_vhandle,  pxy); 

I > 

Crawcln( ) ; 

/»  Display  hatches 

v^lrwl<(screen-vhandle) ; 

vsf— In ter lor (screen— vhandle«  3); 

for  (1  = 0;  1 < 32;  1++) 

I < 

vsf^tyle(screen_whandle,  1+1); 
pxy[0]  = ( (1»8)  » 30)  + 20; 
pxy(l)  = ( (1^8)  » 30)  + 20; 
pxy(2]  = pxy(0)  + 20; 

Pxy(3J  = pxy(l]  + 20; 
wr_rocfl ( screen— vhandle,  pxy); 

> 

Craucin( ) ; 
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Listing  4-1  (continued) 

Fill  area  fills  complex  polygons.  The  shape  In  pxy  array 
« Is  a boutle. 

1 ruU  ( screen_vhandle ) ; 

vsf_peri(neter(screen_vhandlB,  TRUE);  turn  on  perimeter 

wsf^nterior(screenL_vhandlo,  2);  use  pattern  fill 

wsf-style(screerL-vhandle,  9);  brick  pattern 

pxy[0]  = 30;  pxy[l]  = 30; 

pxy[2)  = 150;  pxy(3]  = 150; 

pxy[4)  = 150;  pxy[5]  = 30; 

pxy(6]  = 30;  pxy[7J  = 150; 

pxy[8]  = 30;  pxy(9)  = 30; 

v^flllarea(screeru\;handle,  5,  pxy); 

Craucln( ) ; 

Contour  fill  fills  an  area  already  shown  on  the  display 
v^lruk(screen_s;handle) ; 

vsf^nterlor(screerL.uhandle,  0);  use  hollow  fill 

vsur^ode(screen_v;handle,  MD_TRflNS);  transparent  mode 

pxy[0]  = 30;  pxy[l]  = 30;  draw  overlapping 

pxy [2]  = 100;  pxy [3]  = 100;  rectangles 

V Jba  r ( screerL.vhandl  e , pxy ) ; 
pxy[0]  = 80;  pxy[l)  = 80; 
pxy[2]  = 150;  pxy[3]  = 150; 
vj3ar(screea_vhandle,  pxy); 

v8f^nterlor(screen-vhandle,  3);  /*  use  hatch  fill 

V8f^tyle(8creen_vhandle,  3);  grid  hatch 

v^cntourflll(screen_vhandle,  90,  90,  -1); 

Crawcln( ); 

> 

drabLjclrc( ) 

/««»««««••««»»«»«««««««««•««»«»««»«»«»«««««««««»««« 

Function:  Demonstrate  VDI  circle,  ellipse,  & arc  functions. 

Input:  None. 

Output:  None. 

< 

draw  circle  and  ellipse 
v^l  rwk  ( 8creen_vhandle ) ; 

vsf_lnterlor(screen_vhandle,  2);  pattern  fill 

V8f^tyle(screen^vhandle,  17);  use  wavy  pattern 

v^lrcle(screen_vhandle,  50,  100,  ^0); 
v_^lllpse(screen_vhandle,  150,  100,  40,  75); 

Craucln( ); 

y*  draw  circle  arc  and  ellipse  arc 
v_clruk(screen_vhandle) ; 

v^rc(8crBBrL.vhandle,  50,  100,  40,  600,  1800); 
v_ellarc(8creen_vhandle,  150,  100,  40,  75,  2000,  3500); 
Craucln( ) ; 


VDI  Output  and  FHends  61 


Listing  4-1  (continued) 

/«  drau  circle  pie  and  ellipse  pie 
v_c 1 ruk ( sc r een_vhand 1 e ) ; 

v_ple8llcB(screen^v;handle«  50,  100,  40,  1600,  2100); 
w nl lple(scraBn_vhandle,  150,  100,  40,  75,  3500,  500); 
Craucln( ) ; 


> 

drau^text( ) 

Function:  Demonstrate  VDI  text  drawing  functions. 

Input:  None. 

Output:  None. 

{ 

Int  1; 

MORO  char_helght,  charuuildth,  cell^elght,  cell^ldth; 

MORO  hor^ut,  vert^ut; 

NQRD  attrlb[10]; 
char  8 [32]; 

shou  plain  text  output.  Justified  output,  and  rotation 
v^lruk(screerL.vhandle) ; 

v^text(screerL.vhandle,  30,  40,  "This  Is  u_gtext.”); 
vr_Ju8tlf led(screen^vhandle,  30,  70,  "This  Is  v^ustlfled", 
200,  FftLSE,  FALSE);  no  spacing  changes 

v_justlfled(8creen_vhandle,  30,  100,  "This  Is  unjustified", 
200,  FALSE,  TRUE);  Intercharacter  spacing 

u.JustlflBd(8crBen_uhandle,  30,  130,  "This  Is  v_Ju8tlfled" , 
200,  TRUE,  FALSE);  Interword  spacing 

Vnjustlf led(screeruvhandle,  30,  160,  "This  Is  v_Justlf led" , 
200,  TRUE,  TRUE);  both  adjustments 

vst^otatlon(screen_uhandle,  900); 
v^text(screen_vhandle,  300,  160,  "Text  on  edge."); 
v8t^otatlon(screerL.vhandle,  1600); 

u^text(8creeru.vhandle,  260,  160,  "Upsldedown  text.*); 
ustnJ~otatlon(screen..vhandle,  0); 

Crawcln( ) ; 

shou  current  settings 
v_clruk(&crBBrLnVhandle) ; 
vqt.^ttrlbutes(scrBen_uhandle,  attrlb) ; 
sprlntf(s,  "Current  text  face:  Xd" , attrlb[0)); 
v^text(scraen_vhandle,  10,  20,  s); 
sprlntf(s,  "Current  height  : Xd",  attrlb[7]); 
uugtext(8creen..uhandle,  10,  50,  s); 

Craucln( ) ; 

shou  character  height  In  points  and  absolute  mode 
/»  1 point  & 1 pixel 

V— clrul<(8creen_uhandle) ; 
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U8tiiig4>l  (contlinied) 

V8t-point[screGn_vhandlQ,  1,  &char_wldth,  &char^aight, 
&cell^idth,  &ceU-height) ; 
v-jgtQxt(screen-vhandla,  10,  100,  "This  is  1 point-"); 

v/stJn0lght(8crGeru_vhandlQ,  1,  &char_width,  &char_helght, 
&cell^idth,  &ceii_height) ; 
w-jgtext(8crQen_vhandlB,  10,  190,  "This  is  1 pixel-"); 

Craucin( ) ; 

Default  value  in  point  and  pixel 
v^iruk(screerL.vhandie) ; 

vst_point(8creen_vhandle,  attrib[7],  &char^idth,  &char^eight, 
&CGii_uldth,  &cel 1-height ) ; 

v_gtext(screen-vhandle,  10,  100,  "This  is  default  point."); 

vst_height(8creen_vhandie,  attrib[7],  &char^idth,  &char_height 
&ceii-iJidth,  &cemieight); 

v_gtext(scrGen-vhandle,  10,  190,  "This  is  default  pixel-”); 
Crawcln( ) ; 

10  point  & 10  pixel 

vuclrul<(screen-vhandie) ; 

v8t.point(screerL.vhandie,  10,  &char-uidth,  &char_height, 
&cell-uidth,  &cel 1-height); 

v-gtext(screenL.vhandie,  10,  100,  "This  is  10  point.”); 
v8t-height(screerL.vhandie,  10,  &char-uidth,  &charJieight, 
&celi-uidth,  &cel 1-height ) ; 

v_gtext(screen_vhandle,  10,  190,  "This  is  10  pixels."); 

Craucin( ) ; 

/»  40  point  & 40  pixel 

v^lruk(screen— vhandie) ; 

v8t-point(screen—vhandle,  40,  &char_uidth,  &char-height, 
&ceii^idth,  &cell-height) ; 

v^tGX t( screen— vhandie,  10,  100,  "This  is  40  point.*); 
v8t-hsight(screGn— vhandie,  40,  &char_ width,  &char-height, 
&ceii^idth,  &celi-height) ; 

v-gtBxt(screen-vhandie,  10,  190,  "This  is  40  pixels."); 

Craucin( ) ; 

72  point  & 72  pixel  *y 
v-clruk(screen-vhandle) ; 

vst— point(screen— \4iandle,  72,  &char-width,  &char_ height, 
&ceil^idth,  &cell-height) ; 

v-jgtext(screen— vhandie,  10,  100,  "This  is  72  point."); 

vs t— heigh t(screenu.vhandle,  72,  &char— width,  &char-height, 
&ceii^idth,  &cel  1-height); 

v^tGxt[ screen— vhandie,  10,  190,  "This  is  72  pixels.”); 
vst—height(screen— vhandie,  attrib[7),  &char-width,  &char_height 
&cell_width,  &ceii-height) ; 

Crawcin( ) ; 
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Listliig4-1  (contiimed) 

Font  variations 

v-jclrwk(scrBen-vhanclle) ; 
for  (1  = 0;  1 < 20;  1++) 

{ 

vst-font(8cre8n_vhandle,  1);  set  font 

wqt-name(8cr8Ba-vhandIe,  1,  s);  got  font  name 

v_gt0xt(8crB8nL-vhandle,  (1/10) *150+20,  ( 1X10) *19+20,  s); 

} 

vst— font(8creen_jvhandlo,  attrlb[0));  /*  return  to  system  font  */ 

Craucln( ) ; 

/»  Text  alignment  */ 

v_cirMk(scrB8n_vhandle) ; 

/*  standard  */ 

v_gtBxt(screBn^vhandle,  30,  20,  *Ny *); 

/*  vertical  half  line  */ 

vst-jallgnment(8creen_vhandle,  0,  1,  &hor^ut,  &vert^ut); 
v-jgtBxt(scre8n-vhandle,  B0,  20,  "Hy — *); 

/*  vetlcal  ascent  lino  */ 

v8t^llgnment(screBn_vhandle,  0,  2,  &hor^ut,  &vert-i5Ut); 
v_gtBxt(scre8n_vhandle,  130,  20,  "fty — •); 

/*  vertical  bottom  line  */ 

vst^llgnmBnttscreerL-vhandlB,  0,  3,  ihor-out,  &vert^ut); 
v_gtext(8creen— vhandle,  1B0,  20,  ‘By — *); 

/*  vertical  descent  line  */ 

vst^llgnmentCscreerL-vhandle,  0,  4,  ihor^ut,  &vert_out); 

vugtext(screerL-vhandle,  230,  20,  *0y *); 

/*  vertical  top  line  */ 

vst^llgnment(screerL.vhandle,  0,  5,  &hor_out,  &vert^ut); 

vugtext(8creen_vhandlB,  260,  20,  ”Ty *); 

/*  horizontal  left  */ 

vst_jalignm0nt(scr08n_vhandle,  0,  0,  &hor^ut,  tvert-out); 
v-gtaxt(8creen_vhandlB,  100,  70,  ‘Hleft-jy*); 

/*  horizontal  center  */ 

V8t^lignment(8creen.vhandle,  1,  0,  &hor^ut,  &vert^ut); 
v_jgtBXt(8creen_vhandle,  100,  100,  "Hcenter-y" ) ; 

/*  horizontal  right  »/ 

vst_jallgnmBnt(scrBBn_vhandlB,  2,  0,  ihor^ut,  &vert-out); 
v_jgtBxt(scrBBrLJvhandle,  100,  130,  "Hrlght^‘); 
vst_alignment(screen_vhandle,  0,  0,  &hor^ut,  ivert^ut); 

Craucln( ); 

/*  Show  text  effects  */ 

v^  1 ruk  ( scr  eenL.vhandl  e ) ; 
for  (1=0;  1 < 64;  1++) 

< 

vst^f  fects(screen^vhandle,  1 ) ; 

v^text(8crBen_vhandle,  (i/B)»35+20,  (iXB)»22+20,  "ftby"); 

> 

vst^ffects(screon-vhandlB,0) ; /»  reset  to  normal  */ 

Craucln( ); 

> 
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Ll8tiiig4-1  (continued) 

Main  Program 

main( ) 

{ 

Int  ap_Ld;  application  Init  verify  */' 

WORD  gr^char,  gr^char,  /»  values  for  VDI  handle 

gr_ubox,  gr^box; 

Initialize  6CM  Rccese 


apu.id  = appi^initO;  Initialize  RES  routines 

if  (ap^id  < 0)  no  calls  can  be  made  to  RES 

{ /»  use  GEMDOS  */ 

Cconus("***>  Initialization  Error.  <**»\n“); 

Cconus( "Press  any  key  to  continue.^n” ) ; 

CrawcinO; 

exit(-l);  set  exit  value  to  show  error 

> 

8creen_phandie  = Get  handle  for  screen 

graf^andie(&gr^char,  &grJichar,  &gr^box,  &gr_hbox); 
screen-vhandie  = open.vuork(ecreen.4)handie) ; 
set^creeruattrO;  y*  Set  global  screen  values 

Rppiication  Specific  Routines 


drauLJline( ); 

drauLxectC ) ; 

✓# 

drauuxirc( ) ; 

✓# 

drau.text( ] ; 

/» 

demonstrate  line  types 
rectangle,  bar 
circle,  ellipse,  arc,  pie 
text  functions 


Program  Clean-up  and  Exit 


Wait  for  keyboard  before  exiting  program 

vuci8vuk(screen-.vhandie) ; close  uorkstation 

appi^xitO;  end  program 

) 
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sociated  attributes.  The  draw_ciic()  function  shows  how  to  draw 
circles,  ellipses,  arcs,  and  pies.  Flnalfy,  diaw-testf ) shows  the  various 
text-drawing  ce^abllltles  provided  the  VDI. 

Line  Up:  Function  diaw-Une( ) 

The  diaw_line( ) function  Is  listed  In  the  application  functions  sec- 
tion of  GRAFDEMO.  Basically,  draw_liiie( ) uses  v-plinef ) to  draw  a 
series  of  lines  that  form  an  arrow  (see  Figure  4-1).  To  place  the  arrow 
convenient^  at  any  location  on  the  screen,  draw-linef ) calls  function 
calc-du^O  to  fill  In  the  array  of  points  that  define  the  arrow. 
Function  calc-sliape( ) has  two  parameters.  The  first  Is  an  address  to 
a variable  that  holds  the  total  number  of  points.  The  second  Is  an 
array  Into  which  the  points  are  placed.  The  first  two  elements  of  this 
array  are  set  to  the  coordinates  of  the  first  point  of  the  shape.  The 
remaining  points  are  calculated  with  respect  to  the  location  of  the 
Initial  point  By  passing  new  starting  coordinates  to  calc-shape( ),  the 
calling  function  (In  this  case,  diawJUne( ))  can  place  the  shape  at  any 
location  on  the  screen.  The  reason  for  having  a parameter  to  hold  the 
total  number  of  points  Is  so  that  ca1c-shape( ) can  be  changed  to 
produce  any  shs^.  By  changing  the  calc-ahape( ) function,  the 
draw-line( ) function  can  draw  any  sh£^  you  desire.  Of  course  the 
points  array  must  be  large  enough  to  hold  the  shape.  The  declared 
constant  SHAPE-SIZE  determines  the  overall  size  of  the  shape 
created  In  calc-ahiqiel ). 


Figure  4-1  Pointed  Atiow  Shape 

In  dzaw-line( ),  there  are  two  arrays  labelled  x and  y.  These  arrays 
hold  the  starting  x and  y coordinates  of  the  12  arrows  to  be  drawn. 
To  draw  the  arrows,  the  workstation  Is  cleeued  using  v-clxv^ ).  Then 
for  each  of  the  12  starting  points,  diaw_Une()  sets  the  first  two 
elements  In  array  pxy,  calls  calc_sh^>e( ),  and  peisses  It  the  addresses 
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of  the  variable  count  and  the  pa^  array.  Function  drawJineO  can 
now  ou4>ut  the  arrow  using  the  current  workstation  attributea 
In  the  section  that  shows  the  change  in  line  width,  the  function 
vsL-width( ) is  used  to  set  the  line  width  to  values  1 through  12.  The 
width  of  the  line  is  set  to  i pixels  wide.  When  the  program  is  executed, 
only  odd  values  are  accepted  (see  Figure  4-2).  E^n  values  of  i are  set 
to  the  next  lowest  width  available.  When  all  12  arrows  have  been 
drawn  to  show  the  line-width  setting,  the  program  pauses  to  wait  for 
a to  be  pressed  at  function  Crewdnf ). 


Figure  4-2  Arrows  Showing  Different  Line  Widths 


The  next  set  of  variations  shows  the  different  line  styles  (see  Figure 
4-3).  First,  the  workstation  is  cleared  and  the  line  width  is  reset  to  the 
default  width  (one  pixel  wide).  The  loop  again  produces  12  vd_type() 
arrow  calls  to  set  the  line  type  to  each  of  the  12  values.  The  line  types 
are  indexed  from  0 to  a device-dependent  value.  This  means  that  not 
every  output  device  can  produce  the  same  number  of  different  line 
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slides.  However,  all  devices  have  at  least  stx  different  line  styles  to 
choose  from  (see  Figure  4-4).  Line  type  one  on  the  screen,  for  instance, 
is  a solid  line.  Type  two  is  a long  dash;  type  three  is  a dotted  line;  type 
four  is  a dash-dot  line;  type  five  is  a dash;  and  line  type  six  is  a 
dash-dot-dot  There  is  also  a seventh  line  stjde  that  may  be  defined 
by  the  user.  Some  devices  may  have  the  ability  to  support  even  more 
line  st^es.  Any  line  styles  above  line  index  seven  are  strictfy  device- 
dependent 

The  line  width  is  set  back  to  one  because  a particular  output  device 
may  not  be  able  to  produce  line  stjdes  with  a width  greater  than  one. 
In  particular.  If  you  try  to  put  a line  stjde  on  the  screen  with  a width 
greater  than  one.  only  solid  lines  are  produced.  The  screen  driver  does 
not  have  the  capability  to  produce  thickened  line  styles.  If  you  want 
to  draw  a specific  nonsolid  line,  it  must  have  a width  of  one. 

After  another  pause  at  CiawdnO,  draw_line( ) continues  to  show 
the  various  line-end  stjdes.  The  screen  Is  cleared  and  the  line  width 


04  K)  in  yD  h- 
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Style 

solid 
long  dash 
dot 

dash,  dot 
dash 

dash,  dot,  dot 
user-defined 


16  bits 

Bit  15  Bit  0 

1111111111111111 
11111111111 10000 
1 1 1000001 1 100000 
1111111000111000 
1111111 100000000 
1 1 1 100011001 1000 
1 1 1 10000000011 1 1 


8 - n Device  dependent  line  styles 

ligme  4-4  Line  Stj^es  for  Atari  ST 

Is  set  to  9.  Three  lines  are  then  drawn  to  show  the  three  line- 
end  s^es:  squared,  arrowed,  and  rounded.  Function  v8l_eBds( ) sets 
the  line-end  style.  Line-end  style  zero  means  that  the  end  of  the  line 
has  a square  edge.  Line-end  style  one  puts  an  arrow  at  the  end  of  the 
line.  Line-end  style  two  means  that  the  end  of  the  line  is  rounded. 
These  are  shown  with  three  thickened  lines  in  Figure  4-5. 

0  - Squared  (default) 


1 - Arrow 

2 - Rounded 

Figure  4-5  Line-End  Styles 


Function  draw_Une()  again  pauses  before  showing  the  different 
marker  types.  A marker  type  is  a symbol  used  at  a point  This  is 
especially  useful  when  you  need  to  draw  several  line  graphs  using  the 
same  axes,  for  example,  graphing  the  growth  of  product  A versus 
product  B versus  product  C.  A unique  symbol  (marker)  is  used  to 
denote  the  points  on  each  of  the  three  curves.  A different  marker  type 
is  used  for  each  line. 

The  section  in  diaw_line( ) that  shows  the  different  marker  types 
works  like  the  section  for  tiie  line  widths  and  line  stjdes.  Function 
v_pmarker( ) takes  an  array  of  points  and  places  a marker  at  each 
point  using  the  current  marker  type.  Function  dzaw_Une( ) attempts 
to  output  12  different  marker  types.  There  are  six  different  marker 
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types  that  are  guaranteed  for  all  devices.  Type  one  is  a dot,  type  two 
is  a plus  sign,  type  three  is  an  asterisk,  four  is  a square,  type 
five  is  an  “x”,  and  type  six  is  a diamond  (see  Figure  4-6).  Types  seven 
and  above  are  device-dependent;  if  they  do  not  exist,  marker  type 
three  is  used  as  a default 


1 

. 

Dot 

2 

+ 

Plus 

3 

Asterisk 

4 

□ 

Square 

5 

X 

Diagonal  cross 

6 

O 

Diamond 

7 and  up  ere  device  dependent 

Figiue4-6  MariMT  Types 

The  markers  can  be  scaled  using  the  vBm-height( ) ivmction.  This 
sets  the  height  of  the  maiker  in  terms  of  y-axis  iinlts.  If  the  worksta- 
tion is  using  raster  coordinates,  a y-axis  uiUt  is  simpty  a pixd.  If  on 
the  other  hand  the  workstation  uses  the  normalized  device  coor- 
dinates, a y-axis  unit  is  simpty  the  distance  from  one  discrete  point 
to  the  next  along  the  y-axis,  which  may  be  different  than  one  pixel 
All  VDI  functions  that  refer  to  size,  height  or  width  use  y-axis  or 
x-axis  units.  The  vBm_heig|it( ) function  cannot  be  used  to  scale 
maiker  type  zero,  which  is  always  the  smallest  dot  that  VDI  can 
display  on  the  device.  After  the  various  maiker  types  are  displayed, 
function  dzaw-Une( ) returns  to  maln( ). 

Note  that  most  of  these  output  functions  also  have  an  associated 
color  attribute,  which  is  Ignored  for  the  time  being.  You  can  set  the 
color  for  each  output  object  (for  example,  line  and  maiker)  by  using 
the  £q>propriate  set  color  function.  A more  detailed  discussion  of  color 
is  handled  later  in  Chapter  6. 

Boxed  Itu  Function  dzaw_rect( ) 

ITie  next  function  called  from  main  is  the  dxaw_rect()  function. 
Draw_zect( ) uses  the  draw JkhksC  ) function  located  directly  above 
draw-iect( ) in  the  application  function  section  of  GRAFDEMO. 

The  dxaw-boxesf ) function  clears  the  screen  and  draws  two  rows 
of  four  rectangles.  The  four  rectangles  are  drawn  using  the  four 
different  rectangle  output  functions  supplied  by  VDI:  vr_recll(). 
▼_xbox( ),  v-xfixMcf ),  and  y-barf ).  Flinction  yr_xecfl( ) draws  a filled 
rectangle.  The  y_xbax()  function  draws  a rounded  rectangle.  The 
function  v-zflMn( ) produces  a rounded,  filled  rectangle.  Flnalty,  fimc- 
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tlon  v_bar()  draws  another  filled  rectangle  Why  not  simply  use 
vr-iecfl()  to  produce  a filled  rectangle?  This  is  because  v_ba^). 
designed  to  produce  the  bars  in  a bar  graph,  uses  the  perimeter 
setting.  The  function  VT_recll( ) does  not  draw  a perimeter  regardless 
of  the  perimeter  attribute  setting.  Each  of  these  functions  has  a 
parameter  that  is  an  array  of  four  elements,  which  defines  the  two 
opposite  comers  of  the  rectangle  to  be  drawn  as  in  program  LINES. 

Function  draw_bozes( ) first  clears  the  workstation  and  calls  the 
function  vsfLperimeterf ).  This  fimction  works  with  most  sh£^e  func- 
tions (circles,  ellipses,  rectangles)  to  turn  on  or  off  the  outline 
(perimeter)  attribute.  Outlined  figures  have  a black  line  drawn  aroimd 
their  perimeters  (only  visible  when  the  figures  are  filled  with  a color 
other  than  black).  For  the  first  row  of  four  boxes,  the  perimeter 
attribute  is  off  so  these  boxes  are  not  outlined.  For  the  second  row. 
the  perimeter  attribute  is  on  so  these  boxes  are  outlined. 

The  first  time  draw-boxesO  is  called  from  dzaw-fect(),  the  at- 
tribute settings  are  still  set  from  the  call  to  diaw-line( ).  Primarily, 
the  line  width  last  set  has  a value  of  9.  Note  that  the  perimeter  drawn 
uses  the  current  line-width  setting.  After  the  first  call  to  draw-boxes( ), 
function  draw_rect( ) resets  the  line-drawing  attributes  to  their 
de&ult  values.  A common  programming  mistake  is  assuming  that 
attributes  somehow  reset  themselves  within  a program;  they  don’t! 

Function  dxaw_boxes()  is  called  four  more  times  to  show  the 
various  tnterior:fill  settings  using  the  ysLJnteriorf ) function.  The 
four  interior-fill  settings  are  0 for  hollow  (no  filling),  1 for  solid  (using 
the  current  fill  color),  2 for  pattern  fill,  and  3 for  hatch  fill.  There  is  a 
fifth  interior-fill  setting  using  value  4,  which  allows  the  programmer 
to  specify  a pattern  as  the  fill  pattern.  As  before,  two  sets  of  boxes  are 
drawn  each  time  dxaw_boxes( ) is  called:  the  top  line  with  the  perime- 
ter attribute  turned  off  and  the  second  line  with  the  perimeter  attri- 
bute turned  on. 

Note  that  the  box  produced  by  function  vr_box( ) always  has  a 
perimeter  drawn  independent  of  the  value  of  the  perimeter  attribute; 
this  is  Just  the  opposite  of  vr_iecfl( ).  These  two  functions  ignore  the 
current  perimeter  setting.  This  was  not  readily  apparent  before  using 
different  fill  st^des. 

The  next  section  of  draw_rect( ) displays  the  available  fill  patterns. 
First  the  workstation  is  cleared  and  the  interior  fill  style  is  set  to  style 
2.  pattern  fill.  Even  though  the  program  tries  to  display  32  different 
patterns  on  the  screen;  however,  after  24  defined  patterns,  the 
remaining  patterns  default  to  pattern  1 (see  Figure  4-7).  They  are 
numbered  from  1 to  a device-dependent  value.  For  the  Atari  ST 
screen,  onfy  24  fill  patterns  are  available. 

Function  diaw_xeet()  next  displays  the  fill  hatches.  Again  32 
hatches  are  tried,  but  only  12  different  hatches  are  produced  (see 
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Figure  4-7  Fill  Patterns 


Figure  4-8).  Hatches  are  also  numbered  from  1 to  a device-dependent 
maximum.  For  the  Atari  ST  screen,  only  12  hatches  are  defined. 
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Figure  4-8  Fill  Hatches 

Tlie  VDI  provides  several  functions  to  fill  complex  shapes,  which  are 
demonstrated  next  in  draw_xect().  First  a bow-tie  shape  is  drawn 
and  filled.  The  workstation  is  cleared;  the  perimeter  is  turned  on  so 
that  you  can  see  what  is  being  filled;  the  interior  fill  is  set  to  a pattern 
fill;  and  pattern  style  is  set  to  the  brick  pattern.  The  function 
v_fillaxea()  takes  an  array  of  points  that  define  a pofygon  when 
connected.  The  function  starts  at  the  first  point  draws  a line  to  the 
next  point  and  so  on  until  the  last  point  is  drawn.  When  VDI  reaches 
the  last  point  in  the  array,  it  automatical^  connects  the  first  point 
to  the  last  point  so  that  a closed  polygon  is  created.  Then  the  polygon 
Is  filled  with  the  current  fill  settings  (see  Figure  4-9). 


Figure  4-9  FiUedBowTie 
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The  final  section  of  diaw_rect( ) performs  a contour  fill.  The  contour 
fill  function  starts  at  a point  on  the  display  surface  and  continues  to 
fill  the  bounded  area  surrounding  that  point  It’s  almost  like  pouring 
cement  into  a mold— the  area  Inside  the  mold  (inside  the  bounded 
area)  is  completely  filled  with  the  current  fill  setting.  This  section  first 
clears  the  workstation  and  sets  the  hollow  fill  so  that  the  borders  (the 
mold)  can  be  drawn.  The  writing  mode  Is  set  to  transparent  so  that 
overlapping  figures  do  not  erase  each  other.  Next,  function  T-bar( ) is 
used  to  draw  two  slightty  oveiky>ping  rectangles. 

To  demonstrate  the  contour  fill,  the  interior  fill  st^e  is  set  to  a 
hatch  fill,  and  the  hatch  si^e  is  set  to  3.  The  contour  fill  Is  done  by 
calling  ▼_oontotiiflll( ) specifying  a point  inside  the  area  you  want 
filled  (in  this  case,  a point  in  the  middle  of  the  intersection  of  the  two 
rectangles).  This  function  continues  to  fill  until  it  reaches  a point 
having  the  color  specified  by  the  last  parameter  in  the  function  call. 
Thus,  you  can  fill  to  the  boimdarles  of  a specific  color.  If  the  value  —1 
is  used,  the  filling  stops  when  a color  Is  reached  that  is  different  fix>m 
the  color  at  the  starting  point  Note  that  if  the  area  to  be  filled  Is  not 
completely  bounded,  the  fill  color  ’’spills  out”  vmtU  a boundary  (or  the 
edge  of  the  screen)  Is  reached.  After  the  contour  fill,  draw-xect() 
returns  to  maJn( ). 

Going  In  Circles;  Function  draw-cbcf ) 

The  next  segment  of  GRAFDEMO  deals  with  drawing  circles,  ellipses, 
arcs,  and  pie  sheq>es  of  circles  and  ellipses.  Function  dxaw-dxcf ) first 
draws  a circle  and  an  ellipse.  As  always,  the  workstation  is  cleared 
before  drawing  commences.  The  interior-fill  st^e  is  set  to  a pattern 
fill  and  the  pattern  stjde  is  selected  as  a ”wayy”  pattern.  The  functions 
v-dicleO  and  v_ell4M>e()  draw  the  circle  and  ellipse.  The  two 
parameters  following  the  screen  handle  in  the  function  calls  define 
the  X and  y coordinates  of  the  center  of  the  figures.  The  last  parameter 
of  ▼_drcle( ) (the  number  40  in  this  program)  determines  the  circle’s 
radius.  The  radius  is  measured  in  x coordinate  units.  Likewise,  the 
last  two  parameters  of  v.jeU4^( ) determine  the  radius  in  the  x and 
y direction,  respectlvefy.  The  ellipse  is  calculated  around  those  maxi- 
mum values. 

Next  a circle  arc  and  an  dlipse  arc  are  drawn.  The  parameters  of 
▼_aic( ) are  the  same  as  those  for  v_circle( ),  with  the  addition  of  two 
more  values  representing  the  start  angle  and  end  angle  of  the  arc. 
The  angle  values  are  measured  in  tenths  of  a d^ree.  Thus,  the  values 
800  and  1800  cause  an  arc  to  be  drawn  from  80  degrees  to  180 
degrees.  Zero  d^rees  represents  ’’east”  or  3 o’clock,  90  degrees  Is 
“north”  or  12  o’clock,  and  so  on.  The  reason  that  angles  are  given  in 
tenths  of  degrees  is  simple:  time.  Tenths  of  degrees  can  be  represented 
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Integers  and  still  provide  a relatively  good  amount  of  accuracy.  To 
have  the  same  accuracy  while  measuring  In  degrees  requires  floating 
point  numbers.  It  takes  a computer  much  longer  to  compute  and 
draw  angles  based  on  floating  decimal  point  numbers  than  on  In- 
tegers. With  Integers  the  angles  can  still  be  represented  with  a fair 
degree  of  accuracy  and  the  calculations  can  be  performed  much 
faster.  The  elliptical  arc  function  ▼...ellarcf ) edso  operates  In  much  the 
same  way  as  v-eU^^sef );  again  the  last  two  parameters  represent  the 
starting  and  ending  angles  of  the  arc. 

The  last  part  of  draw_clic( ) draws  circle  and  ellipse  pie  shapes.  The 
function  v_pieslice( ) works  ^e  same  as  the  v_ai«( ) function  except 
that  it  fills  in  the  pie.  Likewise,  v.jellpie( ) works  similaiiy  to  v-ellarcf ) 
and  also  fills  in  the  pie.  Note  that  the  elliptical  pie  Is  drawn  from  350 
d^rees  to  50  degrees  and  goes  through  0 degrees.  Arcs  and  pies  are 
always  drawn  coimterdockwlse;  a pie  drawn  with  a starting  an^e  of 
1 degree  and  an  ending  angle  of  359  degrees  Is  an  almost  complete 
circle.  After  you  enter  program  GRAFDEMO.  try  changing  the  starting 
and  ending  angles. 

Type  Casting:  Function  dzaw_tezt( ) 

The  next  and  final  application  function.  dxaw_text( ),  demonstrates 
the  two  VDI  text  output  functions  v-gteztf ) and  v..jti8tified( ).  The 
function  v_gteact()  slmpty  outputs  a string  at  the  specified  point 
Justified  text  Is  created  by  v-justifiedf ).  Justified  text  has  just 
enough  space  between  each  word  and/or  letter  to  make  the  string  a 
particular  length.  In  this  way.  a paragrsq>h  can  have  a flush  right 
margin.  Both  these  functions  provide  their  output  while  in  the  VDI 
graphics  mode,  which  means  that  the  text  is  Ilteralfy  drawn  on  the 
screen.  Note  that  graphic  text  is  conceptual^  different  from  text 
produced  using  the  piintft ) function  of  C or  any  of  the  BIOS  func- 
tions. GrEq}hlc  text  is  drawn  using  the  current  screen  and  text  at- 
tributes. Therefore,  you  can  change  text  color,  writing  mode,  drawing 
angle,  size,  and  alignment 

The  screen  is  cleared  first  and  v_gtext( ) is  called  to  write  a string. 
The  two  integer  parameters  are  the  x and  y coordinates  of  the  starting 
point  of  the  text  The  v..Jii8tified( ) function  also  specifies  a starting 
point  a character  string,  and  the  let^th  (in  x-axis  units)  into  which 
the  string  must  fit  The  last  two  parameters  determine  how  the  text 
is  to  be  justified.  The  first  parameter  specifies  that  VDI  changes  the 
spacing  between  words  to  justify  the  text  If  this  parameter  is  FALSE. 
VDI  is  not  allowed  to  change  Interword  spacii^.  Ihe  second  parame- 
ter determines  whether  VDI  changes  the  spacing  between  characters 
to  justify  the  text  If  it  is  FALSE.  VDI  does  not  change  intercharacter 
spacing.  The  first  call  to  v-justlfiedf ) has  both  these  parameters  set 
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to  FALSE;  therefore  VDI  is  not  allowed  to  justify  the  text  at  all.  The 
second  call  to  v-justified( ) allows  the  VDI  to  change  intercharacter 
spacing.  Since  a space  is  also  considered  to  be  a character,  the  spaces 
around  each  sp2ice  are  enlarged  as  well  os  the  spaces  between  each 
character.  The  third  call  to  v_justified( ) allows  the  VDI  to  change 
interword  but  not  intercharacter  spacing.  The  last  call  to  v_ju8tified( ) 
in  this  section  allows  VDI  to  change  both  fypes  of  spacing. 

The  section  uses  vst_iotation( ) to  set  the  rotation  angle  for  any 
graphics  text  output  The  angle  is  specified  in  tenths  of  a degree  so 
the  first  call  rotates  text  90  degrees  (not  900).  2^ro  degrees  represents 
level  text.  The  function  v_gtest( ) is  used  to  output  the  text  It  prints 
the  text  at  the  an^e  specified  by  vst-xotationf ).  The  next  call  to 
VBt_rotation( ) rotates  the  text  to  180  degrees  (upside  down);  finally, 
the  rotation  is  set  back  to  zero.  Note  that  not  all  devices  can  rotate 
text.  In  fact  one  of  the  many  pieces  of  information  returned  by 
vq_estend( ) is  whether  the  workstation  has  text  rotation  capability 
and  whether  text  may  be  rotated  at  any  emgle  or  only  in  90-degree 
Increments.  The  Atari  ST  screen  allows  only  90-degree  Increments. 

The  next  section  shows  the  current  settings  used  by  the  text  font 
The  workstation  is  cleared  and  vqt_atliibutes( ) is  called.  Note  that 
functions  beginning  with  “vq”  are  query  functions;  functions  begin- 
ning with  “vs”  are  "set”  functions;  emd  functions  beginning  with  just 
“v”  are  output  functions.  The  vqt_atfaribute8( ) frmctlon  returns  infor- 
mation about  the  current  text  attributes.  These  attributes  include  the 
current  text  face,  text  color,  angle  of  rotation,  horizontal  and  vertical 
alignment  (which  is  soon  discussed),  the  writing  mode,  character 
width  and  height  and  character  cell  width  and  height  Here  just  the 
current  text  face  and  height  are  shown  by  using  v_gtext( ) to  draw 
a string. 

The  next  section  of  dzaw_text()  demonstrates  the  difference  be- 
tween the  various  height  settings.  The  height  of  the  character  is 
mesisured  in  printer’s  points.  One  point  equals  1/72  of  an  inch  and 
measures  from  the  base  line  of  one  line  of  text  to  the  base  line  of  the 
next  line  of  text  The  function  v8t-point( ) sets  the  point  size  to  the 
first  parameter  after  the  screen  handle.  The  remEdnlng  parameters 
are  values  returned  by  VDI  that  contain  the  character  width  and 
height  and  cell  width  and  height  of  the  setting  made  by  vst_point( ). 
If  VDI  cannot  find  the  specified  character  height,  it  automatically 
picks  the  largest  possible  size  smaller  than  the  requested  size.  The 
same  parameters  are  used  by  vst_height( ),  which  sets  the  character 
height  in  y-axis  units.  The  first  calls  in  draw_test( ) set  the  height 
to  one  pixel  and  one  point  You  cem  see  that  this  size  really  doesn’t 
look  like  much.  The  rest  of  this  section  tries  different  point  and  pixd 
sizes;  default  10  pixels,  40  pixels,  and  72  pixels.  Note  that  40  point 
40  pixels.  72  point  and  72  pixels  all  appear  to  be  the  same  size.  Be- 
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cause  these  sizes  don’t  exist,  the  VDI  chooses  the  largest  type  size  it 
can  find. 

Font  variations  are  explored  next.  If  you  don’t  have  any  fonts  loaded 
on  your  ST,  you  only  see  a 6-by-6  ^tem  font  as  the  output  of  this 
section.  The  screen  is  cleared  and  a loop  is  used  to  look  at  the  different 
fonts.  Inside  the  loop,  the  vst_font( ) function  sets  the  font  style.  The 
font  index  is  set  to  the  present  value  of  the  loop  index.  The  inquiry 
function,  vqt_name( ).  retrieves  the  name  and  sijde  of  the  font  This 
function  returns  a 32-character  string.  The  first  16  characters  of  the 
string  contain  the  font  ruime  (or  the  face  name  as  the  VDI  refers  to 
it).  The  next  16  characters  contain  the  font  st^e.  When  this  selection 
has  finished  playing  with  the  various  fonts.  draw_tert( ) returns  to 
system  font  using  the  value  in  attrib[7]  obtained  from  the 
vqt_attributes( ) function  called  earlier. 


Table  4-1:  Face  Names 
and  Slyles 


Face  Names 

Styles 

Swiss  721 

Light 

Swiss  721 

Thin  italic 

Dutch  801 

Roman 

Dutch  801 

Bold  italic 

GEM  can  access  a wide  variety  of  fonts  if  they  are  available  on  your 
system  disk  and  are  available  to  the  device  you  are  using,  llie 
ASSIGN.SYS  file  mentioned  in  Chapter  1 tells  GEM  which  font  files 
are  available  to  the  device.  Before  your  program  can  use  the  fonts,  the 
font  file  must  be  loaded  into  the  workstation  you  are  using  through 
the  vst_loadf6iit8( ) function. 

To  continue  with  draw_tezt(),  the  next  section  adjusts  the  text 
alignment  Alignment  can  be  performed  on  any  of  the  lines  specified 
tty  the  character  cell.  Vertical  text  alignment  is  the  relationship  be- 
tween the  y value  of  the  point  at  which  text  is  drawn  and  the  vertical 
placement  of  the  text  Vertical  text  alignment  can  be  performed  on 
the  base  line  (standard),  half  line,  ascent  line,  bottom  line,  descent 
line,  or  top  line.  For  exeunple,  the  first  call  to  V8t_aligiimeiit( ) causes 
the  base  line  of  the  text  to  be  aligned  on  y value  20.  The  next  call  to 
vst.  ,aHgnment( ) causes  the  half  line  of  the  text  to  be  aligned  on  y 
value  20. 

Horizontal  text  alignment  can  also  be  specified  using  vst-alignmentf ). 
Horizontal  alignment  is  the  relationship  between  the  x coordinate  of 
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the  point  at  which  text  is  drawn  and  the  actual  horizontal  position 
of  the  text  For  example,  horizontal  left  alignment  will  align  the 
furthest  left  point  of  the  string  with  the  x coordinate  of  the  point 
specified.  Center  alignment  centers  the  string  at  the  x coordinate; 
right  alignment  places  the  ftirthest  right  point  of  the  string  at  the  x 
coordinate. 

The  first  parameter  for  vst_aUgnment( ) after  the  screen  handle 
determines  horizontal  alignment  (0  meaning  left,  1 meaning  center, 
and  2 meaning  ri^t).  The  next  parameter  is  vertical  alignment  with 
the  value  0 for  base  line,  1 for  half  line,  2 for  Eiscent  line,  3 for  bottom 
line,  4 for  descent  line,  and  5 for  top  line.  The  dlfierent  values  for 
vertical  alignment  are  shown  first  in  the  output  of  GRAFDEMO.  Note 
that  a left  horizontal  alignment  (the  default)  is  maintained  throughout 
the  various  vertical  changes  and  that  the  vertical  alignment  is  not 
changed  by  new  values  for  the  horizontal  alignment  The  last  two 
parameters  of  vst-aHgnment( ) slmpty  return  the  new  horizontal  and 
vertical  alignment  values  selected,  respectively. 

The  final  workstation  attributes  shown  in  draw_text( ) are  the  text 
effects  available  on  the  ST:  thickened,  light  intensity.  Italicized,  un- 
derlined, outlined,  shadowed,  or  any  combination.  The  vst-efiects( ) 
function  sets  the  text  effect  to  be  used  for  all  subsequent  gr£q>hic  text 
output  based  upon  the  value  of  the  parameter  supplied.  Each  bit  in 
that  value  determines  whether  a particular  attribute  is  set  on  or  off. 
As  shown  in  Table  4-2,  bit  0 corresponds  to  thickened  text  on  or  off; 
bit  1 determines  light  intensity;  bit  2 determines  Italicization;  bit  3 
determines  underlined  text;  and  so.  If  the  bit  has  a 0 value,  that  effect 
is  not  used.  If  the  bit  has  a 1 value,  that  effect  is  active. 


Table  4-2:  Bit  Values 
fbr  Test  Effects 


Bit 

Description 

0 

Thicken 

1 

Light  intensity 

2 

Skew 

3 

Undeiiined 

4 

Outlined 

5 

Shadow 

Since  each  bit  can  be  set  independently,  you  can  combine  various 
effects.  Bits  are  numbered  from  right  to  left;  if  3«>u  want  thickened 
text  only,  the  value  of  the  effect  parameter  is  1.  If  3rou  want  imdeiiined 
and  thickened  text,  bits  0 and  3 have  to  be  on,  giving  the  parameter 
value  of  9 (see  Figure  4-10). 
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Normal 
Thickened 

^ight  Intensity 

Ske  wed 
Underlined 

OotHMd 

Ibiiid©w©d 

Figme  4-10  Teact  ^fects 

There  are  a total  of  64  possible  combinations.  Depending  upon  the 
screen  and  fonts  you  have,  you  may  not  see  all  the  effects.  For 
example,  all  effects  except  shadowing  are  implemented  if  you  use  the 
Intern  font  on  a monochrome  monitor. 

Changit^  GPAFDEBiO 

This  completes  the  GRAFDEMO  program.  If  you  have  not  already  done 
so,  enter  this  program  and  run  it  Once  3«)u  have  it  running,  make 
any  changes  in  it  you  desire.  The  program  has  been  modularly 
designed  so  that  }n>u  can  chemge  and  execute  only  those  areas  you 
want  to  focus  on.  For  example,  try  changing  the  line  drawing  func- 
tions. All  you  need  to  do  is  to  call  diaw_Une( ) from  mainf ) so  you 
can  comment  out  the  other  function  calls. 

Now  is  an  appropriate  time  to  experiment  with  parameter  values, 
become  familiar  with  the  VDI  functions  and  how  they  work,  and  learn 
how  to  reference  the  appendices  of  this  book.  Some  changes  that  3k>u 
can  make  to  GRAFDEMO  are  pla}dng  with  text  point  and  height 
values  and  changing  calc-shiqtef ) to  produce  different  shapes  to  see 
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how  the  array  is  filled  and  used.  (If  you  tiy  changing  calc-shape( ), 
make  stire  you  return  the  proper  number  of  points;  otherwise  VDI 
gets  confused  and  draws  either  too  few  or  too  many  points.) 


Designing  Your  Own  Patterns 


Giving  the  user  the  ability  to  specify  a line  stjde  provides  greater 
variety  to  the  output  of  your  programs.  Designing  your  own  line  or 
fill  patterns  is  much  like  filling  in  a small  bit  map.  For  a line,  the 
pattern  consists  of  a linear  set  of  16  bits  contained  within  one  word 
on  the  ST.  Wherever  a bit  is  set,  a dot  is  said  to  be  at  that  point  on 
the  line.  If  the  bit  is  zero,  no  dot  is  at  that  point  on  the  line.  Of  course, 
the  actual  output  depends  on  the  current  writing  mode.  Figure  4-4 
shows  the  default  line  s^es  available  on  the  ST. 

Designer  Lines 

To  use  your  own  line  style,  you  must  set  the  line  stjde  index  to  7 (the 
user-defined  line  style).  The  actual  line  st^e  is  set  using  the  function 
v8L.iid8ly( ),  the  VDI  Set  Line  User-Defined  Style.  Its  parameters  are 
the  screen  handle  followed  by  a 16-bit  value  (declared  as  WORD  on 
the  Atari),  which  sets  the  bits  for  the  line  s^e. 

Look  at  program  USERTVPE  (see  Listing  4-2).  Function  mainO 
shows  that  this  program  performs  two  basic  tasks:  setting  a user- 
defined  line  st^e  and  setting  a user-defined  fill  pattern.  Under  the 
application  functions  section,  there  is  a function  caUed  8et_line(). 
This  fimction  clears  the  workstation  and  sets  the  line  type  to  the 
user-defined  stj^e  (s^e  7).  The  variable  st^de  (dedared  as  WORD)  is 
set  to  hold  the  line  st^e  that  will  be  the  user-defined  line  style  for 
vsl_udsty( ).  Hocadecimal  notation  is  used  to  set  the  variable  style 
because  it  is  easier  to  convert  from  binary  bits  to  hexadecimal  than 
to  decimal.  For  example,  the  first  line  pattern  used  in  set_line( ) is  a 
series  of  alternating  on  and  off  bits.  This  translates  to  a binary  value 
of  1010101010101010.  This  16-bit  pattern  can  be  broken  up  into 
four  pieces  of  four  bits  each,  that  is,  1010  1010  1010  1010.  E^h 
four-bit  segment  can  represent  16  different  values:  hence  the 
hexadecimal  (base  16)  ^tem.  The  four-bit  pattern  represents  the 
hexadecimal  digit  A Therefore,  the  16-bit  pattern  is  equivalent  to 
AAAA  base  16.  Go  through  the  other  three  line  styles  listed  in 
8et-line( ) and  practice  converting  from  binary  to  hexadecimal.  This 
skill  is  quite  useful  later  on  in  this  book. 

After  each  caU  to  vsLjadstyO  with  new  line  style,  the  function 
draw  Jlnes( ) is  called.  This  function  draws  a series  of  lines  based  on 
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U8tiiig4>2  Program  USEItnPE 

USERTYPE.C  User-definad  styles  program 

This  program  shows  the  use  of  user-defined  line  styles 
and  user-defined  fill  patterns. 


System  Header  Files  & Constants 


ttinclude 

<stdio.h> 

Standard  ID 

ttlnclude 

<osblnd.h> 

✓» 

GEMOOS  routines 

tUnclude 

<gemdsfs.h> 

y* 

GEM  RES  *y 

tUnclude 

<obdefs.h> 

GEM  constants 

Ddefine  FRLSE  0 

ttdefine  TRUE  IFALSE 

GEM  Rppiication  Overhead 

Declare  global  arrays  for  VDI- 

»/ 

typedef 

Int  UORD; 

y* 

UORD  is  16  bits 

UORD 

contrl[12] , 

y* 

VDI  control  array 

intout[128],  intin[12B), 

y* 

VDI  input  arrays 

ptsln(12B],  ptsout[12B]; 

y* 

VDI  output  arrays 

UORD 

sc reen_vhand 1 e , 

/» 

virtual  screen  workstation  ^ 

sc  r een_phandl B , 

y* 

physical  screen  workstation 

screen_rez. 

y* 

screen  resolution  0,1,  or  2 

color^creen. 

yit 

flag  if  color  monitor 

x^ax. 

y* 

max  X screen  coord 

y— max; 

y* 

max  y screen  coord  */ 

Rppiication  Specific  Data 


UORD  pflU-pat[64]  = { 


0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

plane 

1 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

plane 

2 

0X00FF, 

0X00FF, 

0X00FF, 

0X00FF, 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 

0XFF00, 
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U8tiiig4-2  (continiied) 

0XFF00,  0xFF00«  0xFF00,  0xFF00,  plane  3 

0XFF00,  0XFF00,  0XFF00,  0xFF00, 

0X00FF,  0X00FF,  0X00FF,  0X00FF, 

0X00FF,  0X00FF,  0X00FF,  0X00FF, 

0X00FF,  0X00FF,  0X00FF,  0X00FF,  plans  A 

0X00FF,  0X00FF,  0X00FF,  0X00FF, 

0XFF00,  0XFF00,  0XFF00,  0xFF00, 

0XFF00,  0XFF00,  0XFF00,  0xFF00 

>: 

GEM-related  Functions 

UORD  open_vuork(phy 8-handle) 

UQRO  phys-handle; 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys-handle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation, 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/ 

{ 

UQRO  worf^ln(ll]« 

work^ut[57]« 

new_handle;  handle  of  workstation 

Int  1; 

for  (1  s 0;  1 < 10;  i++]  /X  sot  for  default  values 

uork^ln(l)  - 1; 

work_ln[10]  =2;  use  raster  coords 

new_handle  = phys-handle;  use  currently  open  wkstation 

v-apnvuk(work.ln«  &nsu_handle,  worloout); 
return(neu-handle) ; 

> 

se  t-jsc  r BBru^a  1 1 r () 

/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen^vhandle. 

Output:  Sets  x_max,  y-max,  color^screen,  and  screeru^ez. 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ 

{ 

UORD  work— out[57] ; 

vq_Bxtnd(screen— vhandle,  0,  work_out); 
x_jnax  = wori<_out(0] ; 
y-max  - worl<-out(l] ; 

screen— roz  = 6etrsz();  ✓x  0 s lou^  1 = msd,  2 = high 

color-screen  = (screen-rez  < 2);  mono  2,  color  0 or  1 


> 
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Listing  4-2  (continued) 

Pppllcatlan  Functions 


drau— lines (x,y) 
int  x,y; 

Function:  Orau  an  array  of  lines  using  the  current  line  style. 
Input:  X = X coord  to  start  array. 

y = y coord  to  start  array. 

Output:  None. 

< 

UORD  pxyt4): 

Int  1; 


>'•  drau  8 horizontal  lines 


pxy[0]  = x;  pxy[l]  = y; 
pxy(2]  = X + 50;  pxy(3]  = y; 
for  (1=0;  1 < 8;  1++) 

< 

u-pline(screen_uhandie, 

pxy(0]++; 

pxy(l]  +=  3; 

pxy[2]++; 

pxy[3)  = pxy[lj; 

> 


draw  8 uerticai  lines 

pxy(0)  = x;  pxy[l]  = y 

pxyl2)  = pxy[0];  pxy[3]  = y 
for  (1  = 0;  i < B;  i++) 

{ 

v_pi  ine  (screen_v;handie , 
pxy[0]  +=  3; 
pxy[l]++; 
pxy(2]  = pxy[0]; 
pxy[3]++; 

> 


2s  pxy); 

move  start  point  right  by  1 
/*  move  start  point  down  by  3 
moue  end  points  by  same 


40; 

B0; 


2,  pxy); 

move  start  point  right  by  3 
move  start  point  down  by  1 
move  end  points  by  same 


draw  8 diagonal  lines 

pxy[0]  = X + 60;  pxy[l)  = y; 
pxy[2]  = X + 110;  pxy[3]  = y; 
For  (1=0;  i < 8;  1++) 

{ 

v_pline(screerL.vhandle, 

pxy[0]++; 

pxy(l]  +=  3; 

pxy(2]++; 

pxy(3]  +=  10; 


2,  pxy]; 

move  start  point  right  by  1 
move  start  point  down  by  3 
move  end  right  by  1 
move  end  point  down  by  10 
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U8ttng4-2  (continaied) 

> 

return; 

> 


8et^ilne( ) 

/«««««««««««««««««««««««««««««««««««»«««««»«««««««« 
Function:  Sets  user  defined  iine  styies  and  draus  them. 
Input:  None. 

Output:  None. 

{ 

WORD  style; 


yjuz  1 r ul<  ( 8creen.v/hand  ie ) ; 

v/8i.type(screen..uhandie,  7);  use  user-defined  line  styies 

style  = 0XRRRR;  1010101010101010 

V8i^dsty(8creea_uhandie,  style); 
drau^  i nes  (10,10); 

style  s 0XF00F;  1111000000001111 

vsiuudsty(screen_uhandle,  style); 
drau^ines(10,110) ; 

style  = 0X8CEF;  1000110011101111 

v8i^dsty(scrBerL.vhandle,  style); 
dr au_i  1 nes ( 170 , 10 ) ; 

style  = 0XC0F0;  1100000011110000 

vsluudstyCscreeo^vhandie,  style); 
drau^llnes(170,110) ; 

return; 

> 


set_pattern( ) 

Function:  Sets  a user-defined  pattern  and  draus  it. 

Input:  None.  Uses  array  pflll^at. 

Output:  None. 

{ 

WORD  pxy[4]; 

v^lruk(8creenL_v;handle) ; 

vsf— inter lor (screen—vhandie,  4);  use  user  pattern  to  fill 
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Listing  4-2  (continued) 


use  1 plane 

vef^dpat(8creerL.v/handle,  pflli-pat,  1); 
pxy[0]  = 10;  pxy[l]  = 10; 
pxy[2]  = 00;  pxy(3]  = 130; 
vr-rocf 1 (screen^vhandle,  pxy) ; 


USB  2 planes 

vsf-udpat(screen„vhandle,  pflll-pat,  2); 
pxy(0]  = 90;  pxy[l]  = 10; 
pxy(2]  = 160;  pxy[3]  = 130; 
vr— reef UscreerL-vhandla,  pxy); 


use  A planes 

vsf_Judpat(scrBBn_uhandle,  pfill^at,  4); 
pxy[0]  = 170;  pxy(lj  = 10; 
pxy[2]  = 240;  pxy[3)  = 190; 
vr_recfl(screen_vhandle,  pxy); 

return; 

> 

Main  Program 


maln( ) 

{ 

Int  ap_ld;  application  Init  verify 

WORD  grjdchar,  gr_hchar,  values  for  VDI  handle 

gr_ubox,  grj^box; 

Initialize  GEH  Recess 


ap_id  = appl^nitO; 
if  (ap_id  < 0) 

{ 


Initialize  RES  routines  »/ 
no  calls  can  be  made  to  RES 
/*  USB  6EMD0S 


Cconus(****>  Initialization  Error.  <***^n"); 

Cconus( "Press  any  key  to  continue.Nn" ) ; 

Craucin( ) ; 

exit(-l);  set  exit  value  to  shou  error 

> 

screen_phandle  = Get  handle  for  screen 

graf_handle(&gr^char,  &gr«hchar,  &gr-wbox,  &gr_hbox); 
screerL.vhandle  - operL.vuork(6creen_phandle) ; 
set_screen_attr( );  Get  screen  attributes 


Rppllcation  Specific  Routines 
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U8ti]ig4>2  (continued) 

8Gt^lna( ) ; 

Craucin( ) ; 

8Gt_pattBrn(); 

Program  Ciean-up  and  Exit 

Uait  for  keyboard  before  exiting  program 

CraucinO;  GEMDDS  character  input 

v_cl8vwk(8crean_vhandie) ; close  uorketation 

appl^xitO;  and  program 

> 

the  given  coordinates.  Function  diaw-Unest ) outputs  eight  horizon- 
tal lines,  eight  vertical  lines,  and  eight  diagonal  lines,  with  each  line 
in-  each  set  offset  slightly  from  the  previous  line.  When  you  look  at 
the  output,  note  that  the  hoiizont^  lines  don't  start  consistent^. 
Look  at  the  set  of  horizontal  lines  in  the  lower  left  section  of  the 
output  for  instance.  The  line  style  is  set  to  FOOP  in  this  function  call 
(four  ones,  eight  zeroes,  four  ones).  The  first  dash  in  each  line  is  not 
the  same  length;  yet  the  remaining  blanks  and  dashes  are  all  lined 
up.  This  does  not  happen  with  the  vertical  or  diagonal  lines  because 
the  VDI  tries  to  be  extra  efficient  by  copying  the  entire  line  style  word 
for  horizontal  line.  Since  every  16  bits  in  one  line  on  the  screen  repre- 
sents one  word  in  memory,  a new  word  in  memory  starts  every  16 
pixels.  Because  the  line  st^e  is  stored  in  a word,  the  VDI  copies  the 


Edge  of  I Segment  Drawn 

screen 

Flguie4-ll  Horizontal  Line  Alignment 
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line  style  word  to  the  screen  words  that  contain  the  line.  Any  points 
beyond  the  ends  of  the  line  are  not  chcinged.  Figure  4- 1 1 shows  an 
example  of  a line  drawn  on  the  screen.  The  brackets  in  the  figure  show 
the  start  and  endpoints  of  the  line.  Note  that  the  line  style  is  word- 
aligned,  which  means  that  the  start  of  the  line  style  always  corre- 
sponds with  the  start  of  a memory  word.  Word  alignment  is  also  ap- 
plied to  the  system  line  styles  when  drawn  horizontally. 

Having  word-aligned  horizontal  lines  poses  a problem.  If  the  line 
has  spaces  in  it,  it  may  not  appear  to  start  where  you  expect.  As  an 
example,  look  at  the  last  line  in  Figure  4-11.  The  line  should  start  at 
pixel  23,  but  when  it  is  drawn  it  appears  to  start  at  pixel  28. 
Nonhorizontal  lines  do  not  have  this  problem  because  the  VDI  must 
copy  the  line  bit  for  bit  to  the  output. 


Finding  a Pattern 

Lines  by  themselves  are  fairly  straightforward.  You  simply  put  down 
a set  of  bits  on  the  screen  to  form  them.  Patterns,  on  the  other  hand, 
are  somewhat  more  complicated.  A pattern  consists  of  sixteen  16-bit 
words  giving  you  a 16-by-16  matrix  of  bits  (see  Figure  4-12). 


F F 0 0 
FFOO 
F F 0 0 
FFOO 
FFOO 
FFOO 
FFOO 
FFOO 
0 0 F F 
0 0 F F 
0 0 F F 
OOFF 
OOFF 
OOFF 
OOFF 
OOFF 


Figure  4-12  Checkerboard  Pattern 

The  pattern  in  Figure  4-12  forms  a checkerboard.  The  hexadecimal 
code  for  this  pattern  Is  contained  In  the  array  pfiU.pat  listed  in  the 
application-specific  data  section  of  USERTYPE.  E^ch  word  (that  is, 
each  element)  represents  one  line  of  the  pattern.  Note  that  there  are 
four  planes  listed.  Each  plane  is  a fully  defined  pattern.  Planes  are  a 
concept  used  with  color  output  and  are  discussed  further  when  color 
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is  covered.  For  now,  program  USERTYPE  just  demonstrates  the  fact 
that  the  user-defined  fill  pattern  has  the  capaclQr  to  account  for  color 
output  as  well  as  monochrome  output.  Those  of  you  using  a 
monochrome  monitor  see  no  difference.  Those  of  you  using  a color 
monitor  may  wish  to  return  to  this  program  after  color  oulput  Is 
discussed  and  see  how  the  planes  affect  the  output 
The  routine  set.pattem( ) draws  the  pattern  three  times,  each  time 
using  a different  number  of  planes.  Function  set_pattieni( ) starts  by 
clearing  the  screen  and  setting  the  Interior  fill  st^e  to  the  user- 
defined  fill  pattern.  The  function  ) sets  the  user-defined 

pattern  to  the  pattern  held  In  pfill_pat().  The  last  parameter  of 
usC-ut^tf ) Indicates  the  niunber  of  planes  to  use.  When  USERTYPE 
draws  the  pattern,  the  pattern  at  the  edges  of  the  rectangle  is  not 
complete.  Just  as  with  horizontal  lines,  all  patterns  drawn  by  the  VDI 
are  word-aligned.  For  the  most  part,  word  alignment  doesn’t  cause 
any  problems  here  as  it  does  for  horizontal  lines. 

Chatting  USERTYPE 

E^ssentlally  that’s  it  for  the  user-defined  lines  and  patterns.  You  may 
want  to  try  changing  the  user-defined  pattern.  Try  to  make  the  square 
of  the  checkerboard  smaller  or  create  something  completely  different 
You  may  also  want  to  try  emulating  one  of  the  predefined  patterns. 
Patterns  can  be  a lot  of  fun  to  play  with! 


Miilt^le  Workstations 


Multiple  workstations,  the  last  part  of  this  chapter,  complete  the 
discussion  of  attributes  and  VDI  ou^ut  You  have  already  seen  that 
a workstation  Is  a mechanism  the  VDI  uses  to  output  graphic  Images. 
A workstation  has  a set  of  attributes  associated  with  It  Look  In 
Appendix  A for  the  functions  T-opm^)  and  v_opitvwk( ),  which 
open  ph3nsical  and  virtual  workstations,  respective^.  Also  look  at  the 
workstation  Inquiry  function  vq.extnd()  used  In  the  GEM-related 
function  8et_8creen_attr( ) of  the  programs.  Take  particular  notice  of 
the  values  returned  this  function. 

The  open  workstation  functions  returns  “a  slew”  of  Information 
about  the  workstation:  the  maximum  addressable  width  in  the  x and 
y directions;  the  width  and  height  of  the  pixel  the  number  of  line 
types  and  widths  available:  the  number  of  marker  types  and  sizes;  the 
number  of  faces  supported;  the  number  of  patterns;  the  number  of 
hatches;  the  number  of  predefined  colors;  color  capability:  text  rota- 
tion; fill  area  capability;  Input  device  capability:  character  width  and 
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height:  maxinuim  line  width;  and  maximum  and  minimum  marker 
heights.  The  extended  inquiiy  function  vq_eztnd( ) has  two  options: 
it  can  return  the  same  values  as  T-opowkl ) or  it  can  give  extended 
information  such  as  the  type  of  screen  being  used,  the  number  of 
background  colors,  whether  text  effects  are  supported,  the  number  of 
planes  associated  with  the  color,  character  rotation  capability,  and  the 
niunber  of  writing  modes  available. 

The  program  MULWORK  (see  Listing  4-3)  demonstrates  the  use  of 
multiple  workstations.  An  example  of  the  use  of  multiple  workstations 
given  in  Chapter  3 is  the  graphic  design  program  in  which  each  type 
of  output  is  ^ven  its  own  workstation. 

4-3  Program  MULWORK 

MULI40RK.C  Multiple  uorketatlons 


This  program  demonstrates  the  uss  of  multiple  uorketatlons 
to  Implement  sevyeral  sets  of  drawing  attributes  on  the  same 
physical  deulcs.  Also  this  program  Introduces  the  use  of 
the  clipping  rectangle. 


System  Header  Flies  & Constants 


ttinclude 

<8tdio.h> 

/* 

Standard  10 

Itincluds 

<osbind.h> 

6EMD0S  routines 

Ifincluds 

<gamd8fs.h> 

GEM  RES 

Itinclude 

<obdefs.h> 

GEM  constants 

Qdsf ine 

FALSE  0 

Ddef ins 

TRUE  1 FALSE 

GEM  Application  Overhead 


Declare  global  arrays  for  VOX. 

typsdef  Int  UORD; 

UORD  contrl[12], 

intout[12a],  intin[12B], 
ptsln[126],  ptsout[12B]; 

UORD  scrsen_vhandle, 

8creen_phandle, 
screan^rez, 
color^crssn, 
x-max, 
y_max; 


*/- 

/»  UORD  Is  16  bits 
VDI  control  array 
VDI  input  arrays 
VDI  output  arrays 

virtual  screen  workstation 
physical  screen  workstation 
screen  resolution  0,1,  or  2 
flag  if  color  monitor 
max  x screen  coord 
max  y screen  coord 
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Listing  4-3  (contlnned) 

/««•»*«*»***««*»*««««««••««««««««•««•«•«»«««••«»««• 

Application  Specific  Data 

UDRD  handiel,  handles  for  virtual  uks tat ions 

handie2; 

GEM- related  Functions 

t40RD  open_vuork(phys^andle) 

WORD  phys^andle; 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys^andie  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

WORD  uork_ln(U], 

work_out(57], 

new-Jiandie;  /*  handle  of  workstation 

int  1; 

for  (i  = 0;  1 < 10;  i++) 
uork^n[i]  = 1; 
work_ln[10]  = 2; 
neuLJiandie  » physJiandle; 
v^pnvwk(work.in,  &new_handie, 
return(neuLJ^andiB) ; 

> 

80t_screon_attr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  8creerL.vhandle. 

Output:  Sets  x_jnax,  y-inax,  color^creen,  and  8creen_rez. 

{ 

UDRD  uork-out[57] ; 

vq^xtnd[screen_vhandle«  0,  work_out); 
x.jnax  B uork_jaut(0] ; 
y_jnax  = work.jDut[l}; 

screen^rsz  = Getrez();  /»  0 = low,  1 = med,  2 = high 

color^creen  = (scrsen_rez  < 2);  mono  2,  color  0 or  1 

> 


set  for  default  values 

/*  use  rastar  coorcs 
/*  use  currently  open  wkstation  */ 
work.jout) ; 


Application  Functions 
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Ustliig4'3  (continned) 

satl_attrlb( ) 

Function:  Set  attributes  for  virtual  workstation  !• 

Input:  None,  handlel  must  be  set. 

Output:  None.  Sets  attributes. 

V8wr_mode(handlel,  MD_REPLftCE);  /*  replace  writing  mode 
vsl— type (handlel,  3);  dotted  lines 

vs  t.^f  feet  (hand  lei,  8);  underlined  text 

return; 

) 


8et2_attrlb() 

/*«««««««««««««««««««««««««««««««««}(««««««««««««««« 

Function:  Set  attributes  for  virtual  workstation  2. 

Input:  None.  handle2  must  be  set. 

Output:  None.  Sets  attributes. 

( 

vsur_mode(handle2,  MD_TRflNS);  transparent  writing  mode 

vsl^ldth(handle2,  5);  use  thicker  lines 

vst— rotatlon(handle2,  2700);  text  at  270  degrees 

V8f_lnterlor(handle2,  2);  uss  pattern  fill  »/ 

vsf jtyle(handle2,  S);  set  pattern  to  uss 

return; 

> 


draw_rect( ) 

Function:  Draw  rectangles  on  both  workstations. 

Input:  None,  handlel  and  handle2  must  be  set. 

Output:  None. 

{ 

WORD  pxy[4]; 

pxy(0]  = 10;  pxy(l)  = 10; 
pxy[2]  = 75;  pxy[3]  = 125; 

vr— reef 1( hand lei,  pxy);  /*  draw  filled  rectangle 


pxy(0j  = 100;  pxy(l]  =10; 
pxy[2]  = 165;  pxy(3]  = 125; 
vr^ecfl(handle2,  pxy); 

return; 

> 
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LJstiiig4-3  (oontinoed) 

draui-tsxt( ) 

Function:  Draw  text  on  both  workstations. 

Input:  None,  handel  and  handle2  must  be  set. 

Output:  None. 

{ 

v_gtext(handlel,  50,  50,  •This  text  is  drawn  on  workstation  l-“); 
v^text(handi02,  120,  70,  -This  text  is  drawn  on  workstation  2.'); 
return; 

} 


clip.jdemo( ) 

Function:  Demonstrate  clipping  rectangles. 

Input:  None,  handlel  and  handle2  must  be  set. 

Output:  None. 

< 

UORD  pxy(4]; 

pxy(0]  = 20;  pxy[ll  = 20; 
pxy[2]  = 100;  pxy[3]  = 100; 

U8^1ip(handiel,  TRUE,  pxy);  set  clipping  rect  on  1 

pxy[0]  = 100;  pxy[l]  = 20; 
pxy[21  = 180;  pxy[3]  = 100; 

vs-ciip(handle2,  TRUE,  pxy);  sot  clipping  rect  on  2 

v-clruk(screerL.s/handie) ; clear  screen 

pxy[0]  - 100;  pxy(l]  = 20; 
pxy[2]  = 100;  pxyI31  = 100; 

v/^iine(screen_vhandle,  2,  pxy);  draw  line  to  show  edge 

pxy[0]  = 00;  pxy[l]  = 30; 
pxy[2]  = 150;  pxy[3]  = 50; 

vr_recfl(handlol,  pxy);  draw  rect  on  1 over  clip  edge 

pxy[0]  = 50;  pxy[l]  = 60; 
pxy[2]  = 120;  pxy[3]  = 80; 

vr_recfl(handlo2,  pxy);  draw  rect  on  2 ouor  clip  edge 

draw  circle 

u^irclB(handle2,  160,  120,  50); 
return; 


} 


VDI  Output  and  Friends  91 


Li8tiiig4-3  (contintied) 

Main  Program 


main( ) 

< 

int  ap^id;  application  Init  verify 


WORD  gr-jwchar,  grjichar,  values  for  VDI  handle  «/ 

gr-juibox,  gr-hbox; 


WORD  uorl<.in[ll] , uork^ut[57]; 

Initialize  6CM  Recess 

«««  «««  «««««««««  «««*««««««/ 


ap^id  ~ appi.init();  Initialize  RES  routines 

if  (ap^id  < 0)  no  calls  can  be  made  to  RES 

{ /»  use  GEMDOS 

Cccnwe(  Initialization  Error.  <***Nn"); 

Cconus( "Press  any  key  to  continue.^n* ) ; 

Craucin( ); 

exit(-l);  sot  exit  value  to  show  error  */ 

> 

screen.4)handie  s Get  handle  for  screen  */ 

graf^andie(&gr^char,  &gr^char«  &gr^box,  &gr.Jibox); 
screen_vhandie  - open-vuork(8creen^handie) ; 
set-jscreeruattrO ; Get  screen  attributes 


Rppiication  Specific  Routines 


open  two  virtual  workstations 
handlel  = operL.vuork(8crB8n_phandie) ; 
handie2  ~ aperL.vuork(screeruphandie) ; 


setl^attribO ; y*  set  attributes  for  each  */ 

set2-attrib(); 


drauLxect( ) ; 
draw.text( ) ; 
Craucin( ] ; 


draw  rectangles  in  both 
draw  text  in  both  */ 
pause 


clip.jdemo( ) ; show  clipping  rectangle 

Crawcin( ) ; 


92  Atari  ST 


Ustiiig4'3  (continned) 

v_clsvuk(handie2);  close  all  workstations 

v_clsvwk( hand lei) ; 

Program  Clean-up  and  Exit 

«««««««««««««««««««««««««««««•••«««««««««««•»»«««««/ 
t4ait  for  keyboard  before  exiting  program 

Crawcin();  GEMOOS  character  input 

u-jcl6vuk(screerL-vhandie);  close  workstation  «/ 

appl^xitO;  end  program 

> 


MULWORK  also  shows  the  use  of  the  clipping  rectangle.  The  clip- 
ping rectangle  is  a device  used  by  graphic  programs  to  prevent 
drawing  outside  a specific  area  In  other  words,  the  dipping  rectan^e 
dips  (Ignores)  any  output  that  goes  beyond  the  region  of  the  rec- 
tangle. The  clipping  rectangle  itself  is  not  visible  on  the  screen.  It's 
emalogous  to  looking  out  a window:  you  can’t  see  through  the  walls, 
but  3TOU  can  see  through  the  window.  Each  workstation  can  have  its 
own  clipping  rectan^e.  One  use  for  the  dipping  rectangle  is  vdien  the 
graphic  design  program  is  made.  The  workstation  for  the  drawing 
area  has  a clipping  rectangle  that  endoses  just  the  work  area.  In  this 
way,  any  output  written  outeide  the  work  area  is  not  written  into  its 
neighboring  areas.  The  same  goes  for  error  messages  and  settings 
areas. 

In  the  MULWORK  program,  the  onfy  application-specific  data  used 
are  the  variables  to  hold  the  handles  of  the  two  workstations  manipu- 
lated throughout  the  program.  Look  at  main( ).  The  general  flow  of 
MULWORK  first  opens  two  workstations,  sets  the  attributes  for  each 
workstation,  and  puts  output  to  both  workstations.  Finalfy,  the  dip- 
ping rectangle  is  demonstrated. 

The  application-specific  routines  begin  by  opening  two  virtual 
workstations  using  the  open-vwoilc( ) function.  This  function  can  be 
called  for  as  many  virtual  workstations  as  the  VDI  allows,  depending 
on  the  version  of  the  VDI,  the  type  of  machine  used,  and  the  amoimt 
of  memory  available.  Usualfy  four  or  eight  virtual  workstations  can  be 
open  simultaneous^.  In  MULWORK,  there  are  three  virtual  worksta- 
tions and  a physical  workstation  open. 

Once  the  workstations  are  open,  the  first  thing  to  do  is  to  set  the 
attributes  of  each  workstation  using  the  routines  setl.attiib( ) and 
8Ct2_attrib( ).  Workstation  one  uses  the  replace  writing  mode.  The 
width  of  the  lines  used  is  default  (one),  the  line  type  is  a dotted  line, 
and  the  text  effect  is  underlined  text  Workstation  two  uses  a 
transparent  writing  mode.  The  line  width  is  set  slight^  thicker  (five). 
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the  text  is  rotated  at  270  degrees,  and  the  Interior  is  filled  with  fill 
pattern  five. 

Functions  diaw_jrect()  and  dxaw-text()  draw  rectan^es  and  text 
on  both  workstations,  respective^.  The  output  on  workstation  one 
uses  a solid  fill  (the  default);  the  text  Is  drawn  right-side  up  and 
underlined;  and  whatever  Is  drawn  replaces  what  was  on  the  screen. 
The  output  on  workstation  two,  a lattice  fill  pattern,  appears  to  be 
laid  over  what  was  on  the  screen  before  It  That's  why  It  Is  called  the 
"transparent”  writing  mode.  The  text  drawn  at  270  degrees,  Is  also 
transparent  and  so  the  background  shows  through  blank  areas  of  the 
character  cells.  The  text  is  not  imderlined  on  this  workstation. 

After  the  pause  In  mainO,  the  cUp_deino( ) routine  Is  called  to 
create  the  clipping  rectangles.  The  use  of  a clipping  rectangle  can  be 
turned  on  or  off.  Off  Is  the  default  value  when  a workstation  is 
opened.  Setting  a clipping  rectangle  Is  done  In  much  the  same  way 
as  drawing  a rectangle.  The  array  pxy  contains  the  points  that  define 
two  opposite  comers  of  the  rectangle.  The  function  vs-d4>( ) Is  called 
to  set  the  dipping  rectangle.  The  first  parameter  to  vB.clip( ) is  the 
workstation  handle.  The  second  parameter  turns  dipping  on  or  off 
with  TRUE  on  and  FALSE  off.  The  third  parameter  defines  the 
clipping  rectangle  itself.  Function  vs.cl4>( ) is  called  twice  to  create  a 
clipping  rectangle  on  each  workstation.  The  two  clipping  rectangles 
lie  next  to  one  another  but  on  different  workstations.  The  screen  Is 
deared  and  a line  Is  drawn  on  the  edge  between  the  two  clipping 
rectan^es  so  that  you  can  see  the  boundary.  This  line  Is  drawn  on 
the  default  screen  virtual  workstation  so  that  It  Is  not  affected  ty  the 
dipping  rectangles. 

V(fith  two  adjacent  dipping  rectangles  on  the  screen,  cl^_demo( ) 
tries  to  draw  bqrond  the  boundaries  of  each  rectan^e.  First  It  draws 
a rectangle  on  workstation  one  that  goes  beyond  the  right  edge  of  the 
clipping  rectan^e.  The  program’s  output  shows  that  the  rectangle 
stops  right  at  the  boundary.  Another  rectangle  Is  drawn  on  worksta- 
tion two  so  that  it  exceeds  the  left  edge.  Again  the  output  shows  that 
the  rectangle  stops  right  at  the  boundary.  Finally,  a clrde  Is  drawn 
on  workstation  two  with  an  origin  completely  outside  of  the  worksta- 
tion’s botmdary.  However,  Its  radius  causes  some  of  the  clrde  to  fall 
within  the  dipping  rectangle.  Only  that  portion  of  the  clrde  falling 
within  the  dipping  rectangle  Is  shown. 

MULWORK  ends  by  dosing  all  virtual  workstations  used  by  the 
program.  Try  creating  some  functions  that  draw  lines,  text,  or  arcs, 
for  example,  to  experiment  with  the  attributes  on  different  worksta- 
tions. Gk>  Into  the  set  attributes  function  to  change  some  of  the 
attributes  and  see  how  th^  affect  the  output 


CHAPTER  FIVE 


Treasure  Maps 


This  chapter  discusses  bit  maps  and  their  use  In  displaying  Informa- 
tion on  the  screen.  A bit  ms^  is  an  extremely  important  concept  You 
have  already  seen  what  a bit  map  does  and  baslcaUy  how  It  worics.  It 
should  be  stressed  that  a bit  map  is  used  primarily  for  screen  output 
The  Atari  machine  sets  aside  32,000  bytes  of  memory  for  screen  use. 
The  hardware  that  produces  the  screen  images  looks  at  this  memory 
block  to  produce  the  images  shown  on  the  screen. 


Impiementiiig  a Bit 


Computer  memory  on  most  machines  such  as  the  Atari  Is  broken 
down  into  units  called  bytes.  A byte  consists  of  eight  bits  with  each 
bit  set  to  a value  of  zero  or  one.  The  central  processing  unit  of  most 
computers  can  access  memory  as  a single  byte,  a word,  or  some  lar;ger 
unit  On  the  Atari  ST,  a word  consists  of  two  b}rtes  with  the  second 
byte  following  the  first  In  memory.  A larger  unit  that  nrlght  be 
available  Is  called  a page.  On  the  ST.  a page  Is  a block  of  512  bytes. 
Each  byte  in  a computer’s  memory  has  an  address,  which  is  a 
number  ranging  from  zero  to  the  total  number  of  bytes  available  in 
the  ^tem.  When  accessing  a particular  byte,  your  program  may 
specify  any  address  within  this  range.  When  accessing  a particular 
word,  the  address  must  be  an  even  value.  Thus,  the  first  word  In 
memory  consists  of  the  two  bytes  at  euddresses  0 and  1.  The  second 
word  in  memory  is  the  two  t^es  at  addresses  2 and  3.  When  you 
program  In  a language  like  C.  the  compiler  handles  the  restrictions 
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for  accessing  bytes  and  words  In  most  cases.  However,  when  working 
with  the  ST’s  graphics  display,  you  need  to  account  for  certain 
memory  restrictions,  for  example,  the  location  of  the  bit  map  when  It 
Is  accessed  by  the  display  hardware. 

A final  aspect  of  the  bit  map  that  you  need  to  know  Is  how  bits  are 
numbered.  In  a byte,  the  furthest  right  bit  Is  called  bit  number  0 and 
the  furthest  left  bit  Is  bit  7.  In  a word,  the  two  bytes  are  taken  to  be 
one  long  string  of  bits,  so  the  furthest  right  bit  Is  bit  0 and  the 
furthest  left  bit  Is  bit  15. 

The  Bit  Map  in  Memory 

The  graphic  subsystem  of  the  ST  allocates  32,000  contiguous  bytes 
In  memory  for  the  bit  map.  For  each  of  the  32,000  bytes,  one  byte 
follows  the  next  with  no  spaces  In  between.  Figure  5-1  shows  that  the 
32,000-byte  screen  memory  block  czm  reside  zmywhere  In  memory.  For 
processing  efficiency,  the  address  of  the  first  word  In  this  block  must 
lie  on  a half-page  boundary.  This  Is  an  address  evenly  divisible  by 
256.  Because  the  central  processing  unit  on  the  ST  Is  more  efficient 
when  processing  words  than  bjd;es,  all  accesses  to  the  bit  map  are  In 
terms  of  words. 


Address: 


Start  of 
memory 


32,000  bytes 
reserved  for 
screen  bit  map 


End  of 
Memory 


Figure  5-1  Bit  Map  in  Randoni'Access  Memoiy 
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When  the  graphics  hardware  reads  this  section  of  memory,  each 
word  is  mapped  to  the  screen.  Each  pixel  on  the  screen  is  represented 
1^  one  of  the  bits  in  the  bit  map.  The  value  of  the  bit  is  either  1 or 
0,  which  determines  whether  the  pixel  is  “on”  or  “off.”  Figure  5-2 
demonstrates  how  this  is  done. 


Bit  15  Bito 

Address: 

(in  byfts) 

Bas* 

Basa  * 2 


Base  > 80 
Base  * 82 


Base  + 31998 


Bit  Map  in  nemory 


0000011111100000 


1111100000111000 


0001100000011000 

1110011100011000 


0000000000000000 


Rev  0 
Rev  1 


ROV399 

Screen  Image 


Figoie6-2  H^pingofMemoiy  to  Screen  in  Monocfaiome  Mode 


The  beginning  of  a bit  map  has  an  address  called  the  base 
address,  noted  by  the  name  Base  in  Figure  5-2.  The  next  word  is  at 
address  base  plus  two  (two  bytes  per  word);  the  word  after  that  is  at 
address  Base  plus  4;  and  so  on.  A video  display  has  a fixed  niunber 
of  rovtns.  A monochrome  monitor  has  400  rows,  numbered  zero 
through  399.  Within  each  row  is  a set  number  of  pixels.  In  the  case 
of  a monochrome  monitor,  there  are  640  pixels  represented  in  40 
words  (16  bits  per  word  times  40  words  equals  640  bits  or  pixels). 
Each  word  in  a row  is  numbered  from  zero  through  40.  Thus,  the 
screen  is  laid  out  as  a matrix  vidiere  each  pixel  has  a y coordinate  (the 
row  it  is  in)  and  an  x coordinate  (the  word  and  then  particular  bit 
within  that  word). 

However,  memory  is  not  stored  as  a matrix.  Memory  is  stored  in  a 
linear  manner  with  one  byte  following  the  next  from  start  to  finish. 
To  transfer  the  data  in  memory  into  an  image  on  the  screen,  the 
graphics  hardware  is  designed  to  map  the  linear  representation  in 
memory  onto  the  two-dimensional  matrix  of  the  screen.  The  mapping 
process  starts  at  the  first  address  in  the  bit  map  and  the  upper  left 
comer  of  the  screen.  The  first  word  in  the  bit  map  is  placed  onto  the 
first  16  bits  in  the  first  row*,  each  word  contains  16  bits.  The  next 
word  is  placed  in  the  next  16  bits  and  so  on.  This  process  continues 
from  left  to  right  until  the  end  of  the  row  is  reached;  this  is 
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represented  by  the  word  with  the  address  Base  plus  39.  Then  the 
graphics  heu:dware  moves  down  one  row  to  the  next  line  on  the 
screen.  This  line  Is  filled  using  the  next  40  words  in  memory  again 
going  from  left  to  right  The  ms^ping  process  continues  until  all  the 
lines  have  been  mapped  (representing  40  words  per  row  times  400 
rows,  or  32,000  bytes). 

Chapter  1 shows  how  the  screen  works.  The  inside  of  the  screen  is 
coated  with  a phosphor  that  glows  momentailfy  vdien  struck  by  an 
electron.  The  time  required  for  the  glow  to  fade  depends  upon  the 
type  of  phosphor  used  but  is  generally  about  1/30  of  a second. 
Therefore,  the  entire  screen  must  be  rewritten,  or  Threshed,  before 
the  pixels  fade.  If  the  pixels  fade  and  are  then  redrawn,  the  screen 
appears  to  flicker. 

The  time  between  the  start  of  one  refresh  cycle  and  the  start  of  the 
next  cycle  Is  called  the  r^resh  rate.  The  refresh  rate  on  most  screens 
is  1/30  of  a second  (30  Hz).  Thus,  the  graphics  hardv^rare  must  m^ 
the  entire  memoty  to  the  screen  within  this  time  so  that  it  can  start 
the  process  over.  The  Atari  color  monitors  work  at  this  rate.  The  Atari 
monochrome  monitor  works  at  a slightly  faster  rate  (35.6  Hz).  The 
refresh  rate  is  significant  in  animation  programs  because  you  need 
to  know  how  much  time  there  is  between  one  frame  and  the  next 

Note  that  the  process  of  drawing  on  the  screen  actually  consists  of 
changing  the  value  of  a bit  within  the  bit  map.  Therefore,  if  you  set 
a bit  to  1,  the  next  time  the  graphics  hardware  m£q)s  that  bit  to  the 
screen  that  pixel  is  displayed.  To  the  user  it  looks  as  though  the  dot 
is  drawn  on  the  screen. 


Mapping  the  Bits 

Each  time  yoiur  program  draws  a pixel  on  the  screen,  the  graphics 
routine  in  the  computer  performs  a calculation  to  convert  an  (x,y) 
coordinate  into  a memoiy  address  and  a bit  number  within  a word. 
This  occurs  for  every  pixel  your  program  draws,  such  as  when  a 
circle  or  rectangle  is  drawn,  a flgtue  is  filled,  and  a single  pixel  is 
drawn. 

Given  a coordinate  pair  (with  x ranging  from  0 to  639  and  y ranging 
from  0 to  399  for  the  monochrome  screen),  the  address  that  contains 
this  pixel  equals  the  following:  the  base  address  of  the  bit  map  pins 
y times  40  (to  account  for  the  number  of  words  in  the  previous  rows) 
plus  the  Int^er  value  of  x divided  by  16  (since  x represents  the  pixel 
position).  This  is  shown  in  Ek]uation  1.  To  find  the  exact  bit  that 
represents  the  (x,y)  pair,  take  the  remainder  of  x divided  by  16  and 
subtract  this  value  from  15  as  shown  in  Equation  2.  This  subtraction 
is  used  because  bits  £ue  numbered  from  right  to  left  and  from  0 
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through  15.  This  is  the  operation  performed  by  the  graphics  hardware 
each  time  a point  is  drawn  on  the  screen. 

Equation  1 address  = base  + (y  • 40)  + int(x  / 16) 

Equation  2 bit  = 15  — (x  / 16) 


Program  BITMAP 

Lx)ok  at  the  program  BITMAP  shown  in  Listing  5-1.  This  program 
shows  how  you  can  manipulate  the  screen  bit  map  Itself.  Screen  bit 
map  manipulation  must  be  done  through  the  extended  BIOS  (XBIOS) 
routines.  The  XBIOS  is  used  because  the  bit  map  is  a hardware- 
dependent  feature  and  not  accessible  through  GEM. 

There  are  two  addresses  used  by  the  display  hardware.  One  is  the 
physical  base  address,  which  is  the  address  used  by  the  display 
hardware  when  it  needs  to  read  from  the  bit  map  to  put  data  onto 
the  display.  The  other  is  the  logical  base  address,  which  is  used  when 
the  VDI  (or  some  part  of  your  softwcire)  is  writing  to  the  bit  map. 
Program  BITMAP  uses  both  of  these  addresses. 


Memory 


Figure  5-3  Use  of  Logical  and  Physical  Screen  Base  Addresses 


Figure  5-3  shows  what  happens  in  program  BITMAP.  Program 
output  is  placed  into  memoiy  wherever  the  logical  screen  address  is 
pointing.  The  display  hardware  outputs  the  bit  map  pointed  to  by  the 
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physical  screen  base  address.  By  taking  advantage  of  this  situation, 
a program  can  draw  a complex  image  in  the  logical  bit  map.'When 
the  image  is  complete,  the  physical  address  can  be  set  to  point  to  the 
logical  bit  map.  causing  it  to  be  displayed  on  the  screen.  The  end 
result  is  that  the  user  perceives  an  instantaneous  image. 

In  the  program  under  the  application-speciflc  data,  there  are  three 
character  pointers.  The  first,  old^bitmi^,  contains  the  logical  base 
address  of  the  screen  currently  being  used.  The  variable  new_bitmap 
contains  the  address  of  a second  bit  map  to  be  set  up  within  the 
program.  Finally,  the  variable  old_pbase  contains  the  physical  base 
address  of  the  screen  current^  being  used. 

In  mainO,  functions  setJtaseO.  testl().  and  te8t2(),  demonstrate 
some  of  the  uses  and  variations  of  the  screen  bit  m£^.  The  next 
function,  BttceeO,  is  like  the  freed  function  in  C except  that  it  is 
defined  under  GEMDOS.  The  GEMDOS  function  is  preferred  because 
it  is  consistent  with  the  Atari  machine  and  any  other  hardware 
environments  that  use  GEM. 


UstingS-l  Program  BFIMAP 

BITI1^)P.C  Demonstrate  bitmaps 

This  program  shous  hou  a bitmap  is  used  for  screen  display. 


System  Header  Files  & Constants 


tiinciuds  <stdio.h> 
ttinclude  <osbind.h> 
Itinciude  <gamdefs.h> 
ttinclude  <obdsfs.h> 

ttdefine  FALSE  0 

ttdefine  TRUE  IFRLSE 


Standard  10 
GEMDOS  routines 
GEM  RES 
GEM  constants 


GEM  Application  Overhead 


y*  Declare  global  arrays  for  VOI. 

typedef  Int  WORD;  UORD  Is  16  bits  */ 

WORD  contri(12],  y*  VOI  control  array 

intout[128],  intin[128],  >'*  VOI  input  arrays  *y 
ptsin[128],  ptsout[128];  y*  VOI  output  arrays  *y 
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listing  5-1  (continiied) 

UORO  8creen_vhandl8, 

screeriL-phandle, 
screen— rez, 
coXor^creen, 
x-max, 
y-max; 


v/irtual  screen  workstation 
physical  screen  workstation 
✓»  screen  resolution  0,1»  or  2 
flag  if  color  monitor 
max  X screen  coord 
max  y screen  coord 


Application  Specific  Data 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXffXXXX/ 


char  ^oidLbitmap, 
i^nsuJbitmap, 
Xoid-pbase; 


logical  base  of  current  screen 
logical  base  of  new  screen 
y*  physical  base  of  curr.  screen 


/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
GEM- related  Tunctions 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/ 


UORD  open-v/work(phys-handle] 

UORD  phye-handle; 

/XIHHHIXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys-handle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation, 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

{ 

UORD  work-ln[U]« 

work-out [57], 

new-handle;  handle  of  workstation 

Int  i; 


for  (1=0;  i < 10;  i++) 
work— ln[l]  = 1; 
work-ln[10]  = 2; 
new-handle  = phys-handle; 
v^pnvwk(work— in,  inew-handle,  work-Out); 
return(new-handle) ; 


set  for  default  values 


✓X  use  raster  coords 

✓X  use  currently  open  wkstation  */ 


se  t^c  reen-a  1 1 r 0 

/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen-vhandle. 

Output:  Sets  x-max,  y_max,  color^creen,  and  screen— rez. 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ 

< 

UORD  work-out[57] ; 

vq-jBxtnd( screen-vhandle,  0,  workout); 
x-max  = uork-jDut[0] ; 
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ListiDgS-l  (contfamied) 

y_max  = uork^ut(l]; 

screerujrez  = Getrez();  ✓»  0 s low,  1 = mod,  2 = high 

coior^creen  = (screerLxez  < 2);  mono  2,  color  0 or  1 


Application  Functions 
set^a8e( ) 

Function:  Pliocato  memory  for  new  screen  bitmap. 
Input:  None. 

Output:  Sets  olcUiitmap,  neuLjiitmap,  and  old-pbase. 

{ 

tidefine  BOUNDARY  256 
long  x; 

y*  allocate  new  screen  bitmap 
X :=  (iong)(1ailoc(32256L): 
if  (f(x  ^ BOUNDARY)) 

neuubitmap  » (char  *)  x; 

eise 

neuiJjitmap  » (char  *)(x  + 

get  current  vaiues 

oldLbitmap  = (char  *)Logbase(); 

oid-pbase  = (char  *)Phy8base( ) ; 

return; 

> 

tB8tl( ) 

Function:  Show  access  to  second  bitmap. 

Input:  None. 

Output:  None. 

««««««««««««««««««««««««««««««««««»««««««««««««»»«/' 

{ 

int  i; 


get  32  kbytes  */ 
on  half  page  boundary 

y*  move  to  boundary 
(BOUNDARY  > (x  % BOUNDARY))); 


prlntf  ( "Nn^nlogical  = aslx,^nphysicai  = %lx,vnnew  = Jklx^n■, 
oidLbitmap,  oict-pbase,  newJbltmap; 
printf( ‘NnPress  any  key  to  see  new  bitmap^n*); 

Craucin( ) ; 

Setscreen(nehLj3itmap,  neujbitmap,  -1); 
for  (i  = 0;  I < 3276?;  i++) 

*(neuJbitmap4’i)  = i; 

Craucin( ) ; 

Setscreen( oldLbitmap,  oldLbitmap,  ^1); 
return; 


> 
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UstingS-l  (continned) 

test2() 

Function:  Shou  hidden  drawing  on  second  bitmap. 

Input:  None. 

Output;  None. 

{ 

UORD  pxarray[4]; 
int  i; 

printf ( ■^n^nCloaring  now  bitmapvn”); 
Setscreen(neu^itmap,  -IL,  -1); 

U.JC  1 rwk  ( screeruvhandl  8 ) ; 

Set8creen(oldJDitmap,  -IL,  -1); 
printf ( 'VnPress  any  key  to  see'^n*); 

Crawcin( ) ; 

Setscreen(-1L,  newJbitmap,  -1); 

Crawcin( ) ; 

Set8creen(ol<U3itmap,  oldJaitmap,  -1); 

printf ( ■'^nDraulng  In  new  bitmap^n"); 

Crawcin( ) ; 

Setscreen(nBuj3it(napf  -IL,  -1); 
for  (i  = 10;  i <=  1S0;  i +=  IS) 

{ 

pxarray[0]  » i;  pxarray(l]  =1; 
pxarray[2]  = 1+10;  pxarray(3]  = i+10; 
ur-recf  1 (8cre8ru.uhandle,  pxarray) ; 

} 

5etscreen(olcLbitmap,  -IL,  -1); 
printf( '^nNew  screen  ready^n'); 

Crawcin( ); 

5et8creen(neuj3itmap,  nawJsitmap,  -1); 

Crawcin( ) ; 

Setscreen(oldJ3itfflap,  olcLbitmap,  -1); 
return; 

> 

Main  Program 

main( ) 

{ 

Int  ap.Jld;  application  init  verify 

WORD  gr-jwchar,  gr^char,  values  for  VDI  handle 

gr^box.  gr_hbox; 

Initialize  GEM  Pccess 
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Listings*!  (continued) 

ap-ld  = appl.lnit();  Initialize  ftES  routines 

if  (ap_ld  < 0)  no  calls  can  be  made  to  RES 

{ y*  use  GEMDD5 

Cconws(****>  Initialization  Error.  <***\n*); 

Cconws( "Press  any  key  to  continue. ^n* ) ; 

CrawcinO; 

exlt(-l);  set  exit  ualue  to  show  error 

> 

screeruphandle  = Get  handle  for  screen  *y 

graf_handle(&g richer,  &grjichar,  &gr_uhox,  &gr^box); 
screen-uhandle  = open_vuork(screen^handle); 
set.j5croBrLjattr() ; Get  scrosn  attributes 

Rppllcatlon  Specific  Routines 

u.jcurhome  ( screeruuhand  1 e ) ; 
setJbase( ) ; 
testl( ) ; 
test2(); 

Program  Clean-up  and  Exit 

MfreeCneuJsltmap) ; return  memory  *y 

y*  Wait  for  keyboard  before  exiting  program  *y 

CrawcinO;  GEMDOS  character  Input 

v_clsuwk(screen_uhandle) ; y*  close  workstation  *y 
appl^xltO;  end  program  *y 


> 


AUocatu^  a ^ Meqf 

Tlie  routine  set-baseO  allocates  32,000  bytes  of  memoiy  for  a new. 
secondary  screen  bit  map.  There  is  no  input  to  this  routine  and  the 
only  output  is  that  the  function  sets  the  values  of  variables 
old-bitmap,  new-bitmap,  and  old-pbase  mentioned  above.  The 
routine  first  aUocates  32,000  bytes  of  memoiy  using  the  BlallocO 
function.  Note  that  the  function  name  is  capitalized;  this  means  that 
it  is  a GEMDOS  function  and  not  a C-deftned  function.  Mallocf) 
returns  a value  of  type  tong  (representing  an  address  in  memoiy) 
indicated  by  our  (redundant)  long  type  cast  operator.  On  the  Atari 
machine,  longs  and  pointers  are  bo^  32  bits  wide.  A pointer  is  not 
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used  because  GEM  does  not  know  what  type  of  pointer  is  required. 
Therefore,  a type  cast  is  probab^  necessary  in  any  case.  Note  that  the 
argument  used  in  the  call  to  BiallocO  is  32,256,  even  though  the 
program  only  needs  32,000  bytes.  The  reason  is  that  the  base  address 
of  the  screen  bit  m£q>  must  be  on  a half-page  boundary  (divisible  by 
256).  By  adding  on  an  extra  256  bytes,  the  program  has  enough  room 
to  shift  the  base  address  upward  so  that  it  is  divisible  by  256  and 
still  has  32,000  bytes  of  memory  allocated.  Thus,  after  allocating  the 
memory  space,  set_ba8e( ) tests  the  address  of  the  memory  block  to 
see  if  it  falls  on  a half-page  boundary.  If  It  does,  new-bitnuir  is  set  to 
that  address:  otherwise,  new_bitmap  is  set  to  the  next  highest 
half-page  boundary.  The  8et_base()  routine  next  sets  the  variable 
old_bitmi9  to  the  value  of  the  logical  base  address  returned  by  the 
Logbase( ) function  and  then  sets  the  variable  olfL.pbase  to  the  value 
of  the  physical  base  address  returned  by  FfrysbaseC ).  The  function 
LogbaseO  and  PliysbaseO  are  XBIOS  functions  because  they  are 
hardware-dependent  values  set  by  the  ST  when  it  is  turned  on. 
Function  8et-base( ) has  now  set  all  the  base  addresses  needed  for 
this  program. 

Using  the  New  Bit  Map 

The  routine  testlf ) demonstrates  how  to  access  a second  bit  map. 
Function  testl( ) first  prints  the  values  of  the  logical  and  physical  bit 
map  base  addresses.  After  the  user  presses  a key,  function  Setscreenf ) 
is  called.  This  function  has  three  arguments.  The  first  is  the  address 
of  the  logical  screen  bit  map;  the  second  is  the  address  of  the  physical 
screen  bit  map;  and  the  third  is  a value  to  set  the  screen  resolution. 
This  last  value  is  analogous  to  the  value  returned  ty  GetrezO  in 
routine  set-screen-attr( ) where  0 indicates  low  resolution,  1 indi- 
cates medium  resolution,  and  2 indicates  high  resolution.  Any  of  the 
arguments  of  Setscreenf)  may  be  negative  values.  The  use  of  a 
negative  value  Indicates  that  no  action  is  to  be  taken  on  that 
parameter.  For  example,  the  first  call  to  Setscreen( ) sets  the  logical 
and  physical  screen  base  addresses  but  does  not  change  the  screen 
resolution.  The  end  result  of  function  Setscreenf ) changes  the  logical 
address,  the  physical  address,  or  the  screen  resolution.  When  this 
occurs,  the  new  bit  map  will  be  displayed  on  the  screen. 

For  demonstration  purposes,  testl()  performs  a loop  that  simpty 
puts  a number  (the  value  of  the  index)  into  all  locations  of  the  bit 
m£q}  one  byte  at  a time.  Because  the  program  directty  affects  the 
screen’s  bit  map.  the  result  of  this  loop  appears  on  the  screen.  Note 
how  the  screen  reflects  the  binary  values  of  each  location.  For  ex- 
ample. in  row  0 byte  0 (set  to  0 in  the  loop)  contains  eight  white 
pixels.  The  next  b}rte  (set  to  a value  of  one)  contains  seven  white  pixels 
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and  one  black  pixel.  The  next  t^es  continue  this  pattern.  To  end  the 
test,  Setscreen( ) is  cedled  a second  time  to  restore  the  old  screen  bit 
msqp.  which  remains  unaffected  by  the  manipulations  with  the  new 
bit  map. 

The  next  routine,  test2( ).  shows  how  to  set  the  logical  and  physical 
bit  maps  independent^.  This  is  done  so  that  you  can  have  one  image 
displaj^  whUe  your  program  is  drawing  another  image  on  the 
second  bit  map.  The  image  displayed  is  in  the  bit  map  pointed  to  by 
the  physical  base  address;  the  image  drawn  is  pointed  to  by  the  logical 
base  address. 

The  first  step  in  test2( ) is  to  tell  the  user  that  the  other  bit  map 
is  being  cleared.  Function  8et8creen( ) is  called  to  set  the  logical  base 
address  of  the  bit  map  to  new-bitmi^,  but  no  changes  are  made  to 
the  physical  base  or  the  resolution.  The  VDI  function  v_clivdt( ) is 
used  to  clear  the  bit  ma^.  Note  that  in  drawing  the  VDI  uses  the 
logical  base  address,  not  the  physical  base  address.  Thus,  the  physical 
bit  map  (the  one  displayed  to  the  user)  shows  no  change.  This  follows 
the  division  of  purpose  for  each  bit  map  where  the  logical  bit  map 
holds  the  output  from  the  software  and  the  physical  bit  map  produces 
the  image  on  the  screen.  When  the  second  bit  ms^  is  cleared,  you  see 
no  effect  on  the  first  bit  nu^  (the  one  displayed).  After  the  bit  map 
is  cleared,  function  8etscieen( ) is  caUed  to  restore  the  logical  base 
address  so  the  output  of  the  print  statement  appears  on  the  screen. 
After  the  user  presses  a key.  the  pl^ical  base  address  is  set  without 
changing  the  logical  base  address  or  the  resolution.  This  shows  the 
newfy  cleared  bit  map.  After  another  key  is  pressed,  tezt2( ) returns 
the  display  to  the  original  bit  map  old_bitmap. 

Note  that  in  the  calls  to  8etscreen( ).  a constant  of  type  long  is  used 
for  the  values  of  —1.  Because  8etecireen( ) expects  an  address,  the 
parameter  must  fill  all  32  bits  of  information.  If  an  tnt  was  used,  only 
16  bits  of  data  would  be  passed,  causing  the  parameters  to  be  read 
incorrectly. 

The  next  section  of  test2( ) draws  in  the  new  bit  map  while  the  old 
bit  map  is  displayed.  The  image  drawn  is  a set  of  filled  rectangles 
along  a diagonal.  While  the  drawing  takes  place,  the  user  sees  no 
changes  to  the  screen.  Once  the  boxes  have  been  drawn,  the  user 
presses  a key  to  see  them.  When  another  key  is  pressed,  the  original 
bit  map  is  displayed  again. 

Note  that  all  piintff ) calls  start  and  end  with  the  newline  character. 
For  some  reason,  a C output  function,  does  not  work 

precisely  with  changes  made  by  Setscreen( ).  If  there  is  no  newdine 
before  text  is  printed  out  the  text  may  either  appear  on  the  new  or 
the  old  bit  map. 

As  an  operational  side  note,  the  logical  screen  base  address  is  set 
immediately  by  8etscreen( ) because  your  program  wants  to  output  to 
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the  new  bit  setting  as  soon  as  possible.  The  physical  base 
address,  however,  is  set  only  when  the  screen  has  finished  a refresh 
qnde  (that  is,  when  the  last  word  of  the  screen  has  been  drawn). 
During  the  time  between  refresh  cycles,  the  physical  base  address  is 
set  If  this  were  not  the  case  and  the  physical  base  address  was  set 
in  the  middle  of  the  refresh  cyde,  the  top  half  of  the  screen  would 
show  the  old  bit  map  and  the  bottom  half  of  the  screen  the  new 
bit  map. 

Program  BITMAP  shows  that  you  can  set  and  use  a logical  bit  map 
while  looking  at  a physical  bit  map.  This  is  a very  important  feature 
in  animation.  Try  changing  the  defined  boundary  value  of  256  in 
8et_ba8e( ) to  a value  of  127.  Hils  causes  some  rather  interesting  re- 
sults when  the  bit  map  is  changed  from  the  old  bit  map  to  the  new 
bit  ms^. 


Program  ANIMATE 


Program  ANIMATE  is  an  t^pllcatlon  of  the  techniques  learned  in 
program  BITMAP.  Starting  with  the  application-specific  data  in  the 
program  listing  (see  Listing  5-2),  the  constant  SQSIZE  determines  the 
size  of  the  squares  that  are  drawn.  The  pointer  variables  sczeenl  and 
screen2  hold  the  address  of  the  two  screen  bit  maps.  Variable  screml 
holds  the  address  for  the  current  screen  bit  map  (the  one  used  by  the 
system)  and  screen2  is  the  bit  map  created  for  the  program. 

Listing  5-2  Program  ANIMATE 

RNIKRTE.C  Demonstrate  animation  techniques 


This  program  shous  hou  a tuo  bitmaps  are  used  for 
animation. 


System  Header  Files  & Constants 


Standard  10 
GEMDOS  routines 
GEM  RES 
GEM  constants 

ttdeflne  FRL5E  0 

«deflne  TRUE  IFRLSE 


Ulnclude  <stdlo.h> 
ttlnclude  <osblnd.h> 
ttlnclude  <gemdefs.h> 
^Include  <obdefs.h> 


GEM  Rppllcatlon  Overhead 
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Listing  5-2  (contiiiued) 

Declare  global  arrays  for  VOI. 


typedef 

Int  WORD; 

/» 

WORD 

contrl[12] , 

lntout[12e],  lntin(128]. 

/* 

ptsln[12B],  ptsout[12B]; 

/* 

WORD 

sc r een— vhand 1 e , 

/* 

sc  reen..phand  1 e , 

/* 

screen-rez. 

/* 

color— screen. 

/* 

x-max. 

/* 

y-max; 

✓» 

WORD  is  16  bits 
VOI  control  array 
VOI  input  arrays 
VOI  output  arrays 

virtual  screen  workstation 
physical  screen  workstation 
screen  resolution  0,1,  or  2 
flag  if  color  monitor 
max  X screen  coord 
max  y screen  coord 


Rppiication-Specific  Data 

ttdefine  SQSIZE  10  size  of  a square 


char  *screenl, 
*screen2; 


logical  base  of  current  screen 
logical  base  of  new  screen 


GEM- related  Functions 


WORD  operu.vwork(physJiandle) 

WORD  phys^andle; 

/«»««««««  ««««««  ««»«»«««  KMM 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys-handle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

» MINI « ««  KMKX  « « «/ 

{ 

WORD  uork_in[ll), 

work-jout(S?J , 

new-Jiandle;  handle  of  workstation 

int  i; 


for  (1=0;  1 < 10;  1++) 
worl<— ln[i]  = 1; 
work— in[10]  = 2; 
new-hand le  = phys-handle; 
v-opnvwk(work— In,  &nebLiiandle, 
return(neu-handle) ; 


✓»  set  for  default  values 

/*  use  raster  coords 
/*  use  currently  open  wkstation 
wor)<^ut); 


set-jBcreeruattr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen— vhandle. 

Output:  Sets  x— max,  y_max,  color-screen,  and  screen— rez. 

< 

WORD  uorkuout[57] ; 
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Usting  5-2  (continited) 

vq^xtnd(screen^\;handle,  0,  uorloout); 

}cjnax  = uork^ut[0]; 
y-max  = uork_out[l]; 

screen_raz  = Getrez();  0 = icu,  1 = raed,  2 = high 

color^creen  = (screeri-rez  < 2);  mono  2,  color  0 or  1 

> 

Application  Functions 
setJbase( ) 

Function:  Allocate  memory  for  neu  screen  bitmap. 

Input:  None. 

Output:  Sets  screenl,  scrBen2. 

{ 

ttdeflne  BOUNDRRV 
long  x; 

allocate  neu  screen  bitmap 

X = (long)Malloc(32256L) ; get  32  kbytes 

if  (!(x  X BOUNDARY))  on  half  page  boundary  *y 

8creen2  = (char  x; 

else  y*  move  to  boundary  *y 

Bcreen2  = (char  **)(x  + (BOUNDARY  - (x  » BOUNDARY))]; 

y*  get  current  screen  *y 

screenl  = (char  ]Logbase( ) ; 
return; 

> 

drauLJ30x(al,  a2) 

UORD  al[],  a2[]; 

Function:  Drau  tuo  vertical  lines  of  boxes. 

Input:  al  = array  for  first  line  of  boxes. 

a2  = array  for  second  line  of  boxes. 

Output:  None. 

{ 

for  (al[l)  = a2tl)  = 10.  al[3]  = a2[3]  = al[l]  + S0SI2E; 
al[l]  < y-jnax  - 20; 

al(l]+=30,  a2[l)+=30,  al(3)+=30,  a2(3)+=30) 

{ 

vr_recfl (ecreerL_vhandle,  al); 
vr_recfi (screen^vhandle,  a2); 

} 

return; 

> 
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Listing  5-2  (continixed) 

anlcnatelC ) 

Function;  Use  single  bitmap  to  animate  boxes 
Input:  None. 

Output:  None. 

IHUHHf  » ihhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhmhmhhuhhk* 

{ 

WORD  pll[4],  pl2[4];  squares  x coord  »/ 

pll[0]  = SOSIZE  * 2;  square  1 on  screen  1 start 

pll[2]  = pll[0]  + SQSIZE; 

pl2[0]  = x-jnax  - (SQSIZE  2);  square  2 on  screen  1 start 

pl2(2]  = pl2[0]  + SQSIZE; 

v_clrwk(screen_vhandle) ; clear  screen 

y*  set  XDR  draulng  mode 

usur^ode(screen_uhandle,  KD_X0R); 
drauJbox(pll,  pl2);  draw  Initial  squares 

while  (pl2[0]  > SQSIZE+5) 

< 

draw_bax(pll,  pl2); 

pll(0]++;  pll(2]++;  move  along  x values 

pl2(0]-;  pl2(2]-; 
drawJ3ox(pll,  pl2); 

VsyncO; 

} 

> 

anlmate2( ) 

]!«««««« 

Function:  Use  multiple  bitmaps  to  animate  boxes 
Input:  None.  Uses  screenl  and  screen2. 

Output;  None. 

{ 

WORD  pll[4],  pl2(4],  screen  1 squares  x coord 

p21[4]«  p22{4];  screen  2 squares  x coord 

pll[0]  = SQSIZE  * 2;  square  1 on  screen  1 start 

pll[2]  = pll[0]  •(-  SQSIZE; 

pl2[0]  = x_max  - (SQSIZE  * 2);  square  2 on  screen  1 start 

pl2(2]  = pl2[0]  + SQSIZE; 

p21[0]  = (SQSIZE  2 + 1);  square  1 on  screen  2 start 

p21[2]  = p21[0]  + SQSIZE; 

p22[0]  = x_max  - (SQSIZE  *2+1);  /*  square  2 on  screen  2 start 
p22[2]  3 p22[0]  + SQSIZE; 
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Listing  5-2  (continued) 


Set8cr80n(scr00nl,  screenl,  >1); 
v^lruk(screon_vrhandl0) ; cl0ar  scroen 

S0t8cr00n(scr00n2,  scraenZ,  -1); 
v^lruk(8cro0rL.vhandl0) ; claar  8cr00n 

80t  XOR  draulng  moda  »/ 
v;8ur^ad0(8cr0orL.v;handlo,  KD-XOR); 

draw  initial  squaros 


SotscraonCacrsanl,  -IL,  -1); 
draui-J3ox(pll,  pl2); 
Sat8cr00n(8cr00n2,  -IL,  -1); 
drauL-box(p21,  p22); 


uhiio  (pl2(0]  > SQSIZE'i-S) 

{ y*  shoui  nou  and  drau  cn  old 

S0t8croon(8cre0nl,  8croon2,  -1); 

VayncO; 

drau_box(pll,  pl2);  oraao  *y 

pll[0]'»-s2;  pll[2]+=2;  y*  mov/0  along  x axis  ^y 

pl2[0]-=2;  pl2[2J-=2; 

drauJbox(pll,  pl2);  y*  drau  *y 

y*  shou  old  and  drau  on  nou 
58t8croon(8croon2,  scroonl,  -JL); 

Vsync( ) ; 

drau-box(p21,  p22);  y*  eraso 

p2JL{0]+s2;  p21[2J+=2;  y*  move  along  x axis  */ 

p22[0]-=2;  p22[2]-=2; 

drau_box(p2JL,  p22);  y*  drau  *y 

> 

S0tscr0on(8cr0onl,  scroonl,  -1); 

> 


Main  Program 


maln( ) 

{ 

Int  ap_ld;  y*  application  Init  vorlfy  *y 

WORD  gr^char,  gr-hchar,  y*  vaiuos  for  VDI  handio 

gr-ubox,  grJibox; 

Initiaiizo  GEM  Pccoss 


ap.id  = appi^initO;  y*  Initiaiizo  AES  routinas  *y 

if  (ap-^d  < 0)  y*  no  calls  can  be  mado  to  AES  *y 


{ y*  US0  GEMDDS  *y 

Cccnus("***>  Initialization  Error.  <***vn"); 
Cconus( *Pr08s  any  key  to  continue. ^n" ) ; 
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Ustiiig5-2  (continned) 

Craycin( ) ; 

exit(*l);  set  exit  value  to  shou  error 

> 

screeruphandle  » Bet  handle  for  screen 

graf-handle(&gr^char,  &gr^char,  &gr^box«  &gr^box); 
8creen.vhandle  = open_vuork(screeru4>handle) ; 
set^creeajattr( );  Bat  screen  attributes 

f^pplication  Specific  Routines 


QQt-_basQ( ) ; 

animatel( ); 

Craucin(); 
animate2( ); 

Program  Ciean»up  and  Exit 

Hfree(8creen2);  return  memory 

Uait  for  keyboard  before  exiting  program 

Craucin();  6EMD0S  character  input 

v^i8vuk(8creerLJvhandle) ; ciose  workstation 

appl^xitO;  end  program 


> 


In  animation  speed  Is  the  key.  All  chan^  made  to  the  screen 
Images  must  be  made  fast  enough  that  the  ^ does  not  detect 
Individual  Images.  This  Is  the  principle  behind  television  and  motion 
pictures.  For  example,  motion  pictures  are  composed  of  frames  that 
contain  stlU  images.  When  they  are  projected  fast  enough  (about  24 
frames  per  second),  the  Illusion  of  motion  Is  created.  The  same  Is  true 
in  computer  animation.  While  one  Image  Is  displayed,  the  computer 
must  draw  the  next  Image  before  It  Is  displayed.  This  represents  one 
of  the  most  difficult  aspects  of  computer  animation,  especlalfy  In 
Explications  such  as  flight  simulators  where  very  complex  Images 
must  be  generated  within  a very  brief  time. 

ANIMATE  animates  two  colunms  of  small  boxes  that  start  at  each 
edge  of  the  screen  and  move  past  each  other  to  the  opposite  edge.  The 
program  draws  each  column  of  boxes  at  both  edges,  changes  their 
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horizontal  coordinates  a small  amount,  and  draws  them  again  repeat- 
ing this  loop  imtll  the  columns  reach  the  opposite  edge  Of  course, 
the  previous  set  of  boxes  must  be  erased  when  the  new  column  Is 
drawn;  therefore,  ANIMATE  uses  the  XOR  writing  mode  just  as 
program  LINE^. 

In  function  maln( ),  the  first  call  Is  to  set_base( ) to  set  the  base 
values.  Function  8et_l>ase( ) Is  the  same  function  used  in  program 
BITMAP  except  that  In  this  program  the  function  sets  the  variables 
screeiil  and  acnen2.  Next  the  two  einimatlon  functions,  animatelf ) 
and  ani]nate2( ),  are  called.  Tlie  routine  anlmatelf ) shows  the  use  of 
a single  bit  to  animate  the  boxes.  Function  anlmate2( ) uses  two 
bit  maps. 

The  application  function  dzaw-boxf ) Is  used  by  both  animatelf ) 
and  anlmate2( ) to  draw  the  two  vertical  columns  of  boxes.  This 
function  takes  the  coordinates  of  the  top  box  and  draws  all  the  boxes 
In  the  column.  Function  draw-box( ) draws  enough  boxes  to  fill  the 
entire  vertical  height  of  the  screen  as  determined  the  variable 
y-maz  set  in  8et_8creen.^ttT( ).  Having  this  dynamic  drawing  routine 
allows  the  program  to  be  run  on  either  a monochrome  or  color 
monitor. 

The  function  animatelf ) starts  by  setting  the  Initial  coordinates  of 
box  columns  one  and  two  In  arra}^  pll  emd  pl2,  respectively.  Next 
the  workstation  Is  cleared,  the  writing  mode  Is  set  to  XOR  and  the 
Initial  set  of  squares  Is  drawn.  In  the  loop,  the  current  boxes  are 
redrawn  first  (to  erase  them).  Then  the  x coordinates  for  the  new 
columns  are  set  by  Incrementing  the  x value  of  colunm  1 (which 
moves  from  left  to  right)  and  decrementing  the  x value  of  column  2 
(which  moves  from  right  to  left).  When  the  new  x values  have  been 
set,  the  columns  are  drawn.  The  loop  Is  terminated  when  the  second 
column  comes  within  five  plus  one  square  width  pixels  of  the  left  edge 
of  the  screen. 

The  function  Vsync()  Is  called  to  help  give  the  animation  a 
smoother  look.  The  V8f]nic()  function  Is  an  XBIOS  function  and 
causes  the  program  to  pause  until  the  next  refresh  cycle  begins  (called 
a vertical  interrupt).  The  Vsyncf ) function  allows  time  for  the  current 
refresh  cycle  to  complete  so  that  all  the  boxes  are  shown  on  the  screen 
before  they  are  moved.  If  you  take  out  the  Vsync( ) function,  you  see 
a noticeable  flickering  effect  ets  the  boxes  are  drawn. 

The  aniniate2( ) function  Is  similar  to  animatelf ) except  that  two 
bit  maps  are  us^.  Each  bit  msq)  has  two  columns  of  squares  as 
before.  However,  Instead  of  redrawing  the  columns  each  time  on  the 
same  screen  as  the  columns  move  from  one  side  to  the  other,  this 
function  displays  one  bit  map  while  drawing  the  next  Image  on  the 
second  bit  map.  When  the  second  bit  maq)  Is  complete,  the  purposes 
of  the  bit  maps  are  inverted:  the  second  bit  maq)  becomes  the  dis- 
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played  bit  map  (physical  bit  map)  and  the  first  bit  map  becomes  the 
drawing  bit  map  (logical  bit  map).  The  bit  maps  keep  switching  back 
and  forth  until  the  boxes  have  completed  their  journey.  The  boxes 
appear  to  move  in  the  same  manner  as  produced  by  animatelf ). 

In  aniinate2( ).  the  variables  scieenl  and  8creen2  each  point  to  the 
base  of  a different  bit  map-  The  arrays  pll  and  pl2  contain  the  x 
coordinates  of  the  columns  on  screen  one;  the  £irrays  p21  and  p22 
contain  the  x coordinates  of  the  columns  on  screen  two.  As  in  the 
previous  function,  the  initial  coordinates  of  the  boxes  are  set  Screen 
one  uses  the  first  position  of  the  boxes  while  screen  two  uses  the 
next  position  of  the  boxes  as  the  starting  coordinates.  The  next 
position  is  one  pixel  closer  to  the  center  of  the  screen.  Both  screens 
are  cleared,  the  drawing  mode  is  set  to  XOR  and  the  first  columns 
are  drawn  on  each  screen. 

To  start  the  drawing  process,  the  base  addresses  need  to  be  set 
Since  screen  one  is  already  visible,  the  first  step  in  the  loop  is  to 
switch  screens.  The  logical  base  address  is  set  to  scieenl  and  the 
physical  base  address  is  set  to  scieen2.  Now  screen  two  is  visible  and 
screen  one  is  used  for  graphic  output  The  Vqmc( ) function  pauses 
the  program  so  that  the  display  hardware  has  time  to  show  the  new 
image 

While  screen  two  is  displayed.  draw_box()  is  called  to  erase  the 
current  columns  on  screen  one  and  the  new^posltlons  of  these 
columns  are  calculated.  These  new  positions  are  the  next  position 
after  the  image  shown  on  screen  two.  Therefore,  the  x coordinates 
must  be  moved  by  tux)  and  not  Just  one.  Function  draw_box( ) is 
called  to  draw  the  new  columns  on  screen  one  using  the  coordinates 
stored  in  pll  and  pl2.  Now  screen  one  is  displayed  again  and 
drawing  is  done  on  screen  two.  The  procedure  for  drawing  on  screen 
two  is  exactfy  the  same  as  the  one  for  drawing  on  screen  one.  This 
flip-flop  between  display  screens  continues  until  the  columns  have 
made  their  trek  across  the  screen.  At  this  point,  the  screen  addresses 
are  set  to  their  original  state  (that  is.  the  logical  and  physical  base 
addresses  are  both  set  to  screenl  and  the  function  returns  to  main( ). 

The  last  section  of  main( ) calls  the  BAfree( ) function  to  free  up  the 
memory  that  was  allocated  for  the  second  screen  (referenced  by 
variable  screen2).  You  should  always  free  allocated  space  or  GEM 
might  not  be  able  to  use  this  memory  etgaln.  Also,  be  sure  to  use  the 
corresponding  allocation  and  de  allocation  functions  (both  should  be 
from  either  C or  GEMDOS).  The  GEMDOS  functions  are  preferred 
here  because  of  their  guaranteed  portability. 

The  output  of  animate  1 ( ) shows  the  boxes  moving  toward  and  then 
past  each  other.  E^n  though  the  Vsync( ) function  is  in  use.  the 
screen  still  flickers.  This  is  because  the  user  is  actualty  watching  the 
boxes  being  drawn,  erased,  and  redrawn  at  each  location.  Since  the 
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entire  process  Is  visible  on  the  screen,  a flickering  effect  occvirs.  If  onfy 
one  or  two  boxes  are  drawn  instead  of  an  entire  column,  the  time 
required  to  draw  and  erase  the  images  is  reduced  to  the  point  where 
the  screen  does  not  flicker.  However,  if  you  are  creating  a game,  it  is 
most  likefy  that  there  are  20  or  30  objects  to  be  moved  between 
images.  The  more  objects  to  be  moved,  the  more  noticeable  the 
drawing  procedure  becomes. 

The  output  of  ani]nate2( ).  on  the  other  hand,  is  much  smoother 
and  does  not  flicker.  The  time  required  for  the  boxes  to  traverse  the 
screen  is  exactly  the  same  as  in  animatelf ).  but  aniinate2( ) is  much 
more  pleasant  to  view.  You  may  notice  that  the  boxes  tend  to  jump 
at  certain  places.  This  is  because  the  boxes  are  not  drawn  fast  enough 
to  be  placed  on  the  screen  during  the  next  available  refresh  (yde.  In 
other  words,  sometimes  the  new  bit  map  has  to  wait  an  additional 
refresh  cycle  before  it  can  be  placed  on  the  screen.  The  bit  m^s  are 
always  forced  to  wait  for  the  right  time  by  the  Vsyncf ) function. 

ANIMATE  is  quite  straightforward.  It  basicalfy  demonstrates  the 
important  technique  of  swapping  bit  maps.  This  technique  is  used 
later  in  this  book  in  a more  elaborate  animation  program. 

Bit  maps  provide  an  extreme^  powerful  tool  in  the  realm  of  com- 
puter graphics.  In  this  chapter,  you  saw  how  a bit  map  is  transferred 
from  memory  to  the  screen.  You  also  saw  that  the  display  hardware 
uses  two  addresses  when  dealing  with  a bit  map.  The  logical  bit  map 
address  points  to  the  base  of  the  bit  map  to  be  used  for  program 
graphic  output  The  physical  bit  map  address  points  to  the  bit  map 
used  by  the  display  hardware  when  it  is  transferring  an  image  to  the 
screen.  If  the  logical  and  physical  bit  maps  point  to  the  same  location, 
the  program  graphic  ouq>ut  is  immediatdy  displayed  on  the  screen. 
If  the  logical  and  physical  bit  map  addresses  are  different  the 
program  can  create  complex  images  in  the  background  and  have 
these  images  displayed  instantaneoushr  on  the  screen. 

The  bit  maps  covered  in  this  chapter  deal  specifically  with  mono- 
chrome bit  maps.  The  Introduction  of  color  adds  a new  dimension  to 
both  your  program  output  and  the  layout  of  the  bit  map.  Chspter  6 
deals  with  the  use  of  colors  and  specifically  looks  at  the  color  imple- 
mentation on  the  Atari  ST. 


CHAPTER  SIX 


Colors  of  the  Rainbow 


This  chapter  shows  how  the  Atari  machine  produces  color  graphics 
from  a bit  map,  how  color  Is  represented  In  memory  and  converted 
to  a screen  Image,  and  how  the  VDl  and  extended  BIOS  functions 
alter  the  color  display.  This  chapter  also  Includes  a demonstration 
program  showing  some  of  the  capabilities  of  the  color  display. 


Color  Display  Implementation 


A monochrome  screen  Is  coated  with  a phosphor  on  the  Inside  that 
glows  when  struck  with  an  electron.  Because  only  one  type  of  phos- 
phor Is  used,  only  two  colors  can  be  displayed:  either  black  (no  color) 
or  whlte/green/amber  (depending  upon  the  phosphor  used).  A color 
screen  uses  the  three  primary  colors  of  light,  which  can  be  com- 
bined to  create  other  colors  as  described  In  Chapter  2.  On  the  Atari 
ST,  the  Intensity  of  each  color  can  range  from  0 (meaning  the  color 
Is  not  used,  that  Is,  off)  to  7 (Indicating  the  highest  Intensity).  This 
gives  eight  different  Intensity  levels  for  each  color.  Therefore,  the  Atari 
ST  Is  c£^able  of  dlsplajdng  512  different  colors:  8X8X8. 

Because  there  are  eight  Intensity  levels  for  a color,  each  pixel  would 
require  at  least  three  bits  to  store  the  Intensity  level  of  one  color. 
Since  there  are  three  colors  with  three  bits  for  each  color,  the  com- 
puter system  would  need  to  store  nine  bits  of  Information  for  eveiy 
pixel  on  the  screen,  which  would  use  too  much  memory.  Even  at  the 
low  resolution  setting  of  320-by-200  pixels,  the  ^tem  would  need 
72,000  bytes  to  store  a screen  Image:  320  pixels  X 200  pixels  X 9 bits 
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-5-  8 bits  per  byte.  In  other  words,  the  ^tem  would  need  over  twice 
as  much  memory  space  to  represent  one-fourth  the  resolution  of  a 
monochrome  screen,  which  uses  only  32.000  bytes  in  high  resolution 
mode.  In  addition  to  this,  a group  of  nine  bits  cannot  be  stored 
efficiently  because  bytes  are  only  8 bits  long  whereas  words  are  16 
bits  long. 

Monochrome  Bit  Maps 

Atari  has  devised  a mechanism  to  get  around  this  problem.  The 
monochrome  bit  map  is  quite  straightforward.  Figure  6-1  depicts  this. 


Screen 


In  high  resolution  mode,  the  ^tem  requires  exacts  32.000  bytes 
to  represent  the  entire  screen  in  a bit  msq).  The  memoiy  allocated  for 
this  bit  map  is  shown  in  Figure  6-2.  There  is  a base  address  for  the 
start  of  the  bit  map  and  the  words  within  the  bit  map  are  contiguous. 
The  first  40  words  represent  the  first  row  on  the  screen:  the  noct  40 
the  second  row;  and  so  on. 

The  Color  JPiolette 

On  the  Atari  ST.  the  color  monitor  would  require  over  twice  the 
amoimt  of  memory  needed  for  the  monochrome  monitor  to  represent 
512  different  colors  at  one-quarter  of  the  resolution.  To  keep  the  bit 
map  for  the  display  within  32.000  bytes.  Atari  chose  a method  that 
aUows  only  16  colors  to  be  accessible  for  display  at  any  one  time. 
These  16  colors  are  placed  in  what  is  called  a color  palette. 
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Plane  Row  Vord 

0 0 0 

0 0 1 

0 0 2 


0 1 0 


Address 


0110010110001 110 


(in  bytes) 

Base 
Base  + 2 


Base  + 80 


Figure  6'2  Memory  Layout  of  a Monochrome  Bit  Map 


The  color  palette  is  a block  of  16  words  in  memory.  Each  word 
represents  a different  color  entry.  The  colors  are  numbered  from  0 to 
15.  Each  entry  in  the  color  palette  contains  the  intensity  levels  for 
each  of  the  three  primary  colors  used  to  create  this  color  entry  (see 
Figure  6-3). 

In  each  word,  the  first  four  bits  represent  the  blue  intensity,  the 
next  four  bits  represent  the  green  intensity,  and  the  next  four  bits 
represent  the  red  intensity.  Since  only  three  bits  are  required  to 
describe  the  eight  different  levels  of  intensity,  the  last  bit  in  each 
four-bit  group  is  not  used.  The  last  four  bits  of  the  word  are  also 
unused.  For  example,  the  color  black  has  a palette  entry  that  is  all 
zeros  (0x0000  in  hexadecimal).  The  color  white  has  the  full  intensity 
for  each  of  the  three  colors  (0x0777  in  hexadecimal). 

The  color  palette  shown  in  Figure  6-3  is  actually  the  default  color 
palette  of  the  authors  computer.  Colors  0 and  15  should  always  be 
set  so  that  color  0 has  the  highest  intensity  (white)  and  color  15  uses 
no  colors  (black).  The  entries  in  the  palette  can  be  modified  by  a 
program,  which  is  demonstrated  shortly. 

How  does  using  a color  palette  reduce  the  memory  requirements  of 
the  bit  map?  Since  the  palette  has  only  16  colors,  you  don’t  need  9 
bits  to  represent  each  pixel  on  the  screen.  To  represent  16  different 
colors,  you  need  only  4 bits  to  represent  a number  between  0 and  15. 
On  the  low  resolution  screen,  the  system  uses  32,000  bytes:  320  pixels 
X 200  pixels  X 4 bits  per  pixel  8 bits  per  byte.  This  Is  the  same 
amount  of  memory  needed  for  the  high  resolution  monochrome  dis- 
play. 
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Figure  6-3  Color  Palette 


Planes 

There  are  different  ways  to  represent  the  four-bit  color  palette  index 
in  the  bit  map.  The  Atari  ST  uses  a rather  interesting  method  called 
planes. 

The  color  bit  map  can  be  thought  of  as  a simple  extension  of  the 
monochrome  bit  map  shown  in  Figure  6-L  Since  it  takes  four  bits  to 
describe  the  color  of  a single  pixel,  the  color  bit  map  uses  four  planes 
(see  Figure  6-4).  Each  plane  is  a bit  map  representation  of  the  screen. 
Thus,  the  furthest  left  bit  in  the  first  byte  of  each  plane  corresponds 
to  the  upper  left  pixel  on  the  screen.  By  combining  bit  settings  in 
each  of  the  four  planes  for  that  particular  pixel,  a palette  entry  index 
can  be  constructed.  For  example,  in  Figure  6-4.  the  first  pixel  has  a 
palette  index  of  0 because  bit  15  of  the  first  word  in  each  plane  is  set 
to  0.  The  seventh  pixel  has  a palette  entry  index  of  7 because  of  the 
bit  settings  in  each  plane. 

Similar  to  the  monochrome  bit  map.  the  color  bit  map  is  laid  out 
in  a contiguous  block  of  memory.  The  first  word  in  each  plane 
describes  the  first  16  pixels  on  the  screen,  the  next  word  in  each 
plane  describes  the  next  16  pixels,  and  so  on.  The  planes  are  arranged 
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Figure  6-4  Planes  Used  In  a Color  Bit  Map 


in  an  interleaved  fashion.  This  means  that  the  first  word  of  plane  0 
Is  followed  by  the  first  word  of  plane  1.  the  first  word  of  plane  2.  and 
then  the  first  word  of  plane  3.  The  next  word  in  memory  corresponds 
to  the  second  word  of  plane  0.  followed  by  the  second  word  of  plane 
1,  and  so  on  (see  Figure  6-5). 
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Figure  6-5  Memory  Layout  of  a Color  Bit  Map 
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The  mapping  of  bits  from  a row  and  word  position  to  pixels  on  the 
screen  is  analogous  to  the  procedure  used  for  a monochrome  bit  map. 
It  proceeds  from  left  to  right  on  the  screen  and  from  top  to  bottom. 
The  low  resolution  color  screen  is  320  pixels  wide  and  has  200  rows. 
Taking  the  Interleaving  of  planes  into  consideration,  row  0 occupies 
the  first  160  bytes  in  the  bit  map:  20  words  per  row  per  plane  X 4 
planes.  Row  1 occupies  the  next  160  bytes,  and  so  on. 

Figure  6-6  shows  an  example  of  how  color  output  is  produced.  First, 
the  appropriate  bit  is  extracted  from  each  plane  in  the  bit  map.  These 
bits  are  placed  together  to  obtain  the  color  palette  index.  Note  that 
plane  3 is  the  most  significant  bit  of  the  color  index  and  plane  0 the 
least  significant  bit.  In  Figure  6-6,  the  value  0111  references  color 
index  7 in  the  palette.  The  value  taken  from  the  palette  determines 
the  red,  green,  and  blue  Intensities  to  be  output.  This  mix  of  colors 
is  then  placed  at  the  corresponding  pixel  on  the  screen. 
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Figure  6-6  Convertiiig  Bit  Map  Planes  to  Color  Output 


Color  Versus  Monochrome 


In  the  programs  used  so  far,  there  has  been  no  distinction  between 
color  and  monochrome  screens.  However,  there  is  a difference.  If  you 
try  to  write  color  Images  to  a monochrome  screen  using  the  VDI,  it 
will  map  any  nonwhite  colors  as  black.  Thus,  portions  of  your  image 
using  different  colors  are  not  distinguishable  from  one  another.  This 
Is  why  It  is  important  to  use  the  inquiry  functions  as  used  in 
set_8creen_attr( ) to  determine  the  type  of  screen  in  use.  If  you  are 
not  using  the  VDI.  the  value  of  bit  0 in  the  color  palette  entry  is  used 
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to  determine  If  the  pixel  Is  on  or  off  when  ou^ut  to  a monochrome 
screen. 

If  you  output  an  image  designed  for  a monochrome  monitor  to  a 
color  screen,  the  result  really  won’t  be  too  much  different  except  that 
the  colors  are  white  and  some  other  color.  For  example,  if  you  use 
colors  0 and  1 the  image  includes  white  and  whatever  color  entry  1 
is  set  to  be.  If  you  want  to  be  sure  black  and  white  are  output  whether 
or  not  you  use  a color  monitor,  specify  color  0 for  white  and  color  15 
for  black.  As  default  values,  color  0 is  the  background  color  (generally 
white)  and  color  15  is  black.  Using  this  combination  you  get  black- 
and-white  Images  on  all  types  of  monitors.  Of  course,  if  your  program 
is  using  the  VDI  for  output,  you  may  use  color  0 and  any  other  color 
because  the  VDI  converts  any  nonwhite  color  to  black. 


Resolution 


Another  variable  on  the  video  display  of  the  ST  is  the  resolution  of 
the  image.  There  are  three  resolution  values:  high,  medium,  and  low. 
In  high  resolution,  the  screen  has  640  pixels  across  and  400  pixels 
down.  Mediiun  resolution  has  640  pixels  across  and  200  pixels  down, 
and  low  resolution  has  320  pixels  across  and  200  pixels  down.  High 
resolution  is  only  available  on  the  monochrome  monitor  for  two 
reasons.  First  a color  monitor  with  this  resolution  is  very  expensive 
to  produce.  Second,  the  bit  msp  required  would  consume  too  much 
memoiy.  The  low  resolution  mode  uses  four  planes  to  allow  the 
display  of  any  of  16  colors  at  one  time.  Medium  resolution  has  twice 
the  number  of  pixels  as  low  resolution.  However,  to  fit  the  bit  map 
into  32,000  bytes,  only  half  the  number  of  planes  can  be  used.  This 
means  that  onfy  four  colors  are  available  in  medium  resolution.  These 
colors  are  the  first  four  palette  entries. 


Program  COLOR 

Program  COLOR  is  a demonstration  program  that  uses  most  of  the 
GEM  and  XBIOS  functions  for  altering  the  colors  displayed  on  the 
screen.  Listing  6-1  shows  the  usual  header  files  and  GEM  ^plication 
overhead.  In  the  section  for  application-specific  data,  there  are  three 
constants:  RED,  GREEN,  and  BLUE,  which  are  used  to  reference  the 
array  elements  of  the  parameter  array  for  the  VDI  set_color( ) func- 
tion. 
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Listing  6-1  Program  COLOR 

COLOR.C  Color  demonstration  program 

This  program  shows  the  use  of  the  color  palette. 


ttlnclude 

<stdlo.h> 

ttlnclude 

<osbind.h> 

ttlnclude 

<gemdefs.h> 

ttlnciude 

<obdefs.h> 

ttdeflne 

FRLSE  0 

ttdeflne 

TRUE  !l 

Standard  10 
/»  6EMD0S  routines 
GEM  structures 
GEM  write  modes 


GEM  Rppllcatlon  Overhead 


Declare  global  arrays  for  VOI.  */ 
typedef  int  UORD; 

WORD  contri[12], 

lntout[128]«  lntln[12B], 
ptsln[12B],  ptsout[12B]; 


WORD  Is  16  bits 
VDI  control  array 
VDI  input  arrays 
VDI  output  arrays 


sc  r eerL.vhand  1 e , 

/* 

sc  r een_phand 1 e , 

screen^rez. 

/» 

color.jscreen. 

/» 

x-jnax. 

/» 

y-jnax; 

virtual  screen  workstation 
physical  screen  workstation 
screen  resolution  0,1,  or  2 *>’ 
flag  if  color  monitor  *>' 
max  X screen  coord 
max  y screen  coord 


Rppllcatlon  Specific  Data 


define  colors 

ttdeflne  RED  0 

lldeflne  GREEN  1 

ndeflne  BLUE  2 

rotating  palette 
WORD  pal-jwheel[]  = { 


0x000, 

0x002, 

0x020, 

0x200, 

0x022, 

0x202, 

0x220, 

0x222 

0X000, 

0x111, 

0x222, 

0x333, 

0x^^^, 

0x555, 

0x6G6, 

0x222 

0x000, 

0x002, 

0x020, 

0x200, 

0x022, 

0x202, 

0x220, 

0x222 

0x000, 

0x111, 

0x222, 

0x333, 

0x444, 

0x555, 

0X6G6, 

0x227 

>; 


/*  current  palette 
WORD  save-43ai(16] ; 
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Usdiig6-1  (oontinned) 

GEM-related  Functions 


WORD  open-vuork(phys-Jiandle) 

WORD  phys^andls; 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys-handle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

WORD  uorl<.ln[ll] , 

worl<_Dut(57) , 

newJiandle;  handle  of  workstation 

int  i; 


for  (1  = 0;  1 < 10;  i++) 
worl<-ln[i]  = 1; 
work— ln[10]  = 2; 
naw-handlo  = phys-handle; 
v-Opnvwk(worl<— In,  &newJiandle,  worl<-out); 
return (new-handle) ; 


/»  sot  for  default  values 


use  raster  coords 
y*  use  currently  open  wkstation  *y 


set^creerL^ttr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen_vhandle. 

Output:  Sets  x_jnax,  y-jnax,  color-screen,  and  screen-rez. 

< 

WORD  work.jaut(57] ; 

vq-extnd(screen_vhandle,  0,  workuout); 
x_max  = work-out [0]; 
y-max  = work^jout  [ 1 ] ; 

scroon-rez  = Getrez();  ✓»  0 = low,  1 = med,  2 = high 

color-screen  = (screen_rez  < 2);  y*  mono  2,  color  0 or  1 

> 

Pppllcatlon  Functions 

checl<— tab  1 e ( handle ) 

WORD  handle; 

Function:  Check  If  color  lookup  table  is  supported. 

Input:  handle  = handle  of  device  to  check. 
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U8tiiig6-1  (continued) 

Output:  0 = table  supported. 

1 = not  supported. 

< 

UORD  uork_out[S?] ; 

vq^xtnd(handle,  1,  workuout);  do  extended  inquire 

rBturn(uork_jout[5) ) ; return  flag 

> 

8hobL43alette( ) 

Function:  Draw  a set  of  squares  to  show  current  color  settings. 
Input;  None. 

Output:  None. 

{ 

register  i; 

UORD  pxy[4]; 

for  (1=0;  1 < 16;  i++)  ST  supports  up  to  16  colors 

{ 

pxy[0]  . (i  X 4)  » 40  + 20; 

pxy[l]  = (1  ^ 4)  » 40  20; 

pxy[2]  = pxy[0]  + 3S; 

pxy[3]  = pxy[l]  + 35; 

v/sf.jcolor(screerL.vhandle,  i);  set  Fill  color 
vr„recfl(screerL.vhandle,  pxy); 

> 

> 

change_palette( ) 

/'ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft#«««ftft««««««Kffff««|H( 

Function:  Change  palette  index  3 using  VOI  function. 

Input:  None. 

Output:  None. 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft«ftftK«/ 

{ 

WORD  rgb[3),  /’»  meu  settings 

srgb[3);  saved  settings  *y 

long  delta;  use  long  to  slow  down 

inquire  current  value  for  index  3 »/' 
vq^olor(screen_vhandle,  3,  0,  srgb); 

lnitiall2e 
rgb(RED)  = 0; 
rgb[GREEN)  = 0; 
rgb[BLUE)  = 0; 
delta  = 1; 
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UstliigS'l  (continued) 

loop  around  colors 

for  (rgb[BLUE]  = 0;  rgb(BLUE]  < 1000;  rgb[BLUE)  +«  delta) 
V8^olor(screenu.v;handle«  3,  rgb); 

for  (rgb[RED]  = 0,  rgb[GREEN]  « 0;  rgb(REO]  < 1000; 

rgb  [RED]  +-  delta,  rgb  [GREEN]  -i--  delta) 
u8ucolor(screerL.v;handle,  3,  rgb); 

for  (;  rgb[BLUE]  > 0;  rgb[BLUE]  -=  delta,  rgb[GREEN]  -=  delta) 
vs_color(screen_v;handle,  3,  rgb); 

for  (;  rgb[REO]  > 0;  rgb[RED]  -=  delta) 
us^olor(screen.vhandle,  3,  rgb); 

CrauclnO ; 

U8^olor(screen_whandl0,  3,  srgb);  re8tore  color 

> 

rot^alette( ) 

Tunctlon:  Use  Xbols  call  to  set  entire  palette. 

Input:  None.  Uses  arrag  pal.jdheel[ ]• 

Output:  None. 

{ 

register  1; 

save  current  palette 

for  (1  = 0;  1 < 16;  1++) 

eave-43al[l]  = Setcolor(l,  -1);  read  current  value 

for  (1  = 0;  1 < IG;  1++) 

< 

Setpalette(&pal.juiheel[  1 ] ) ; set  base  of  palette 

shouL^paletteO ; 

Crawcln( ); 

> 

SetpaletteCsave^al) ; restore  original 

> 


/«««««««««««««««««««««««««««««««««««««««««««««««««« 

Main  Program 

maln( ) 

{ 

Int  ap-.ld; 

WORD  gr-juichar,  gr-hchar, 
gr^box,  grjibox; 


application  inlt  verify 
values  for  VDI  handle 
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Listing  6-1  (continued) 

Initialize  GEM  Rcceos 

ap-ld  » appl-lnit();  Initialize  ftES  routines 

if  (ap^d  < 0)  no  calls  can  be  made  to  RES 

{ /»  use  GEMDOS 

Cconws("»»»>  Initialization  Error.  <*<^«Nn"); 
Cconus(*Press  any  key  to  continua.^n" ); 

Craucin( ) ; 

exit(-l);  set  exit  value  to  show  error 

> 

screon_phandle  = Got  handle  for  screen 

graf_handlo(igr-wchar,  &gr«hchar,  &gr_wbox,  &gr-hbox); 
screen^uhandle  - open.juuork(8creeiX43handle) ; 
set-scroBR-jattrO ; y*  Get  screen  attributes 


Rppiication  Specific  Routines 


1 ruk  ( screerL.vhandl  e ) ; 

if  ( lchecl<.tabiB(screea.vhandle) ) y*  check  for  color  table  *y 

{ 

printf ("***>  Color  look-up  table  not  supported  <***^n“); 
printf ( ”Color  palette  function  will  have  no  effectin'*); 
printf ( "Pross  any  key^n*); 

Craucin( ) ; 

> 

vsf— interior(8crBoruvhandle,  1);  y*  set  solid  fill  *y 

showL-palotteO ; y*  show  current  palette  *y 

Craucin( ) ; 

change-paietteO ; reset  values  *y 

Crawcin( ) ; 
rot^aiette( ) ; 


Program  Clean-up  and  Exit 

y*  Walt  for  keyboard  before  exiting  program  *y 

CraucinO;  y*  GEMDOS  character  input 

vucl8vwk(scrBen^vhandie) ; y*  close  workstation  *y 

appi-Bxit();  y*  end  program  *y 

> 
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The  array  paLjwfaeel  is  used  as  a set  of  palette  entries.  Each  line  of 
the  initialization  contains  eight  hexadecimal  numbers.  Each  number 
determines  a particular  color  for  that  color  index.  For  example,  the 
first  entry  has  a value  of  zero,  which  means  that  the  red,  green,  and 
blue  intensities  are  all  zero  and  yield  the  color  black.  The  second  entry 
has  a hexadecimal  value  0x007,  which  means  that  red  and  green  have 
an  intensity  of  zero  and  blue  has  an  intensity  of  7 (the  highest 
intensity  available)  producing  the  color  bright  blue.  The  value  0x070 
represents  green,  0x700  represents  red,  0x077  represents  a green  and 
blue  mixture,  and  so  on.  The  last  entry  in  the  first  row,  0x777, 
represents  white.  In  the  next  row,  the  values  go  through  a simple 
pattern  from  0x000,  0x111,  0x222,  to  0x777;  this  represents  ei^t 
different  shades  of  gray  from  black  to  white.  The  last  two  lines  repeat 
the  first  two  lines. 

The  laist  application-specific  data  variable  is  the  array  save_paL 
This  array  is  used  to  save  the  current  palette  at  the  start  of  the 
program. 

Under  the  application-specific  routines  in  function  malnO,  the 
workstation  is  cleared  using  v_cltwk( ).  Next  function  dieck-ttible( ) 
is  called.  This  function  checks  to  see  if  a color  table  is  supported  by 
the  VDI  for  this  device.  A color  table  Is  a VDI  concept  that  provides  a 
device-independent  method  for  determining  the  color  settings.  There 
are  two  different  levels  of  color  manipulation  in  the  ST.  One  is  the 
VDI  and  the  other  is  direct  changes  to  the  color  palette.  The  VDI 
handles  converting  a color  requested  ty  the  program  to  the  best- 
matched  color  on  the  device.  For  example,  on  the  Atari  color  display, 
the  VDI  uses  a table  to  convert  the  VDI  colors  to  the  palette  colors 
used  by  the  display  hardware.  However,  on  a color  slide  producer,  the 
VDI  uses  the  lookup  table  to  find  the  color  set  by  the  user  and  outputs 
this  color  to  the  device  (slide  producers  general^  have  an  extremely 
large  range  of  colors).  The  other  level  of  color  graphics  manipulation 
is  through  the  Atari  display  hardware.  This  is  done  by  actually 
accessing  the  color  palette  Itself.  By  changing  the  color  palette,  you 
can  alter  the  palette  as  a whole  or  set  an  individual  color. 

The  check-table( ) routine  uses  the  vq_extnd( ) function  to  do  an 
extended  inquiry.  Note  that  the  second  parameter  is  a 1 for  the 
vq_e3ctnd( ) function.  This  requests  the  extended  values  to  be  returned 
rather  than  simpfy  the  open  workstation  values.  Compare  this  usage 
to  the  way  the  vq_extnd( ) function  is  used  in  set_screen^ttr( ).  The 
returned  values  of  the  extended  inquiry  are  put  into  the  array  ele- 
ments. Element  5 contains  the  flag  as  to  wdiether  or  not  the  color 
table  is  supported.  Element  5 contains  TRUE  if  a color  table  exists, 
FALSE  otherwise.  If  the  table  Is  not  supported,  the  VDI  function 
set-coloif ) has  no  effect 

After  checking  the  color  table  support,  maiii( ) continues  by  setting 
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the  Interior-fill  mode  to  a solid  fill  using  vsf_interior( ).  Then  function 
diow-palette( ) is  used  to  draw  a set  of  16  rectangles  with  each 
rectan^e  drawn  in  a different  VDI  color. 

The  next  function  called  by  inaiii( ) is  change-palettef ).  This  uses 
the  VDI  set  color  function.  vs_color( ),  to  change  a particular  color  of 
the  palette.  The  vb.jco1oi(  ) function  has  three  j>arameters.  The  first 
parameter  is,  as  usual,  the  handle  of  the  workstation.  The  second 
parameter  is  the  color  number  to  be  changed.  The  last  parameter  is 
an  array  of  three  elements.  Ihe  first  dement  in  the  array  is  the  red 
intensity,  the  second  is  the  green  intensity,  and  the  third  is  the  blue 
intensity. 

The  W)I  color  table  is  somewhsit  different  than  the  Atari  color 
palette.  The  VDI  color  table  is  as  large  as  necessary  for  the  VDI  to 
support  all  of  the  colors  available  for  that  device.  Each  color  has  a red, 
green,  and  blue  intensity;  however,  the  intensity  levels  range  from  0 
to  1000  with  0 the  lowest  and  1000  the  highest  intensity.  The 
intensity  levels  are  relative  to  the  actual  levels  that  can  be  produced. 
For  ^cample,  on  the  Atari  color  display,  a VDI  intensity  of  1000 
equates  to  an  intensity  levd  of  7 in  the  color  palette.  A palette 
intensity  levd  of  5 is  equivalent  to  a VDI  intensity  of  714.  Thus,  the 
VDI  can  support  a device  that  has  coarse  intensity  settings  such  as 
the  color  display,  as  well  as  a device  with  very  fine  intensity  settings 
such  as  a color  slide  producer. 

In  chaiige_palette( ),  the  first  step  is  to  inquire  about  color  table 
entry  number  3 using  the  vq_color( ) function.  The  jrarameters  of 
yq_color()  are  the  workstation  handle,  the  color  number,  and  a 
number  which  tdls  the  function  what  values  to  return.  A parameter 
of  0 (as  used  here)  indicates  that  the  set  values  of  the  color  are  to  be 
returned.  If  the  parameter  is  a 1.  the  “realized”  values  are  returned. 
These  are  the  values  that  are  seen  on  the  device,  since  the  device 
probabty  does  not  have  1000  levels  of  intensities.  The  realized  value 
shows  what  intensity  value  is  actualty  shown  on  the  screen.  The  last 
parameter  of  the  function  is  a three-dement  array,  which  hdds  the 
intensity  levels  for  each  of  the  three  colors. 

The  next  step  is  to  initialize  the  intensity  levels  for  the  red,  green, 
and  blue  colors.  After  this  initialization,  change_palette( ) loops 
through  a series  of  color  changes.  These  changes  correspond  to 
traveling  around  the  color  cube  shown  in  Figure  6-7.  Starting  at  the 
lower  left  comer,  the  first  loop  in  change_palette( ) increases  the  blue 
intensity,  vdilch  is  equivalent  to  moving  up  the  left  edge  of  the  cube. 
The  next  loop  moves  diagonally  across  the  top  by  increasing  the  red 
and  green  intensity  levels.  The  third  loop  moves  diagonally  across  the 
rl^t  face  by  decreasing  the  blue  and  green  intensity  levels.  The  final 
loop  decreases  the  red  intensity  level  to  return  to  the  starting  posi- 
tion. Figure  6-7  shows  eight  intensity  levds  because  these  are  the 
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realized  Intensity  levels.  When  this  program  runs,  a black  rectan^e 
goes  through  these  color  transformations.  Tlie  last  statement  in 
cfaange-paletteC ) restores  color  3 to  its  original  setting. 
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Figure  6-7  Color  Cube 

The  next  function  called  from  main( ) is  the  rot_palette( ) function. 
This  rotates  colors  within  the  palette  by  using  XBIOS  routines.  The 
first  thing  to  do  is  to  save  the  current  palette  settings  by  calling  the 
Setcolorf ) function  for  each  of  the  16  color  entries.  The  first  parame- 
ter of  Setcolorf ) is  the  color  index.  The  second  is  the  intensity  combi- 
nation to  place  at  that  color  entry.  Setcolorf ) returns  the  intensity 
value  of  the  palette  entry  before  It  changes  an}rthing.  If  a negative  value 
is  used  for  the  color  intensity,  no  change  is  made.  The  n^atlve 
peuameter  is  used  to  read  the  current  values  and  store  them  in  the 
sa:ve-pal  array.  The  next  step  Is  to  rotate  the  palette  colors.  This  is 
done  through  the  SetpaletteO  function.  Function  SetyaletteO  has 
onty  one  parameter  the  address  of  a 16-word  block  of  memory. 
Se^Mlettef ) actually  sets  the  16  palette  entries  by  placing  those  16 
words  into  the  palette.  Tlie  palette  for  the  ST  is  actualty  a reserved 
portion  of  memory  used  by  the  display  hardware. 
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To  rotate  the  palette,  a loop  is  used.  The  loop  calls  Setpalette( ) with 
the  address  of  the  next  element  In  array  paL«dieeL  Then  function 
show-palette( ) is  called  to  draw  the  set  of  16  squares.  Actually,  the 
Sef^>alette( ) function  affects  the  current  display  so  the  show_palette( ) 
call  is  unnecessaiy.  The  reason  the  new  palette  colors  take  effect 
immediately  is  that  the  graphics  hardware  needs  to  access  the  palette 
to  refresh  the  screen.  Therefore,  if  3«>u  change  the  palette  colors,  the 
displayed  colors  also  change  on  the  next  refresh  cycle. 

Now  it's  obvious  why  the  pal-wheel  array  has  32  entries. 
Set-palette( ) is  called  with  the  address  of  each  of  the  first  16  ele- 
ments in  array  paL-wheel.  This  address  is  used  as  the  “base  address” 
of  a 16-word  block  in  memoiy.  Thus,  for  each  address,  there  must  be 
at  least  16  entries  defined  following  that  address.  The  first  call  to 
Set_palette( ) assigns  the  first  through  sixteenth  elements  in  the 
array  to  the  palette;  the  second  call  assigns  the  second  through 
seventeenth  elements  in  the  arrajr;  and  so  on  until  the  sixteenth  call 
assigns  the  sixteenth  through  thirty-second  elements  in  the  array.  At 
the  end  of  rot_palette( ).  Set_palette( ) is  called  once  more  to  restore 
the  original  palette  colors. 

IVhen  the  program  is  running,  notice  that  rot_palette( ) does  not 
display  the  colors  in  the  order  thqr  are  listed  in  the  array.  From  the 
program  listing  where  the  paL-vdieel  array  is  defined,  you  would 
think:  the  first  line  of  boxes  displayed  would  be  black,  blue,  green, 
2md  red;  the  second  line  cyan,  magenta,  yeUow,  and  white;  the  next 
two  lines  various  shades  of  gray.  Instead  of  this  predicted  pattern,  you 
see  a mix  of  the  various  colors  that  are  suppo^  to  be  shown.  The 
reason  is  that  program  COLOR  mixes  the  use  of  VDI  output  and 
XBIOS  changes.  The  VDI  is  used  in  8how_palette( ) to  draw  the 
display  and  XBIOS  is  used  to  set  the  colors  of  the  display.  The  VDI 
color  indices  are  not  the  same  as  the  palette  color  indices.  The 
matching  of  the  VDI  and  palette  color  indices  is  shown  in  Figure  6-8. 


VDI 

Palette 

VDI 

Palette 


Figme  6-8  of  VDI  Color  Index  to  Haidnaie  Palette  Index 
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The  VDI  indexes  numbered  0 to  15  reference  the  actual  palette 
numbers  shown  In  the  lower  half  of  the  boxes.  Note  that  the  back- 
ground color  (always  color  0)  does  change  in  accordance  with  the 
sequence  of  colors  in  the  paL.whed  array.  This  is  to  be  expected 
bemuse  VDI  color  0 and  palette  color  0 use  the  same  color.  Remember 
that  color  0 is  always  used  as  the  background  color  because  objects 
are  most  easify  erased  by  redrawing  them  with  the  background  color. 
This  is  seen  on  the  palette  dl^Iay  where  the  box  drawn  in  color  0 is 
not  visible  on  the  screen. 

An  interesting  exercise  is  to  take  out  the  8how-.palette( ) call  in 
xot-palette( ).  You  see  that  the  Setpalette( ) call  replaces  the  palette  in 
between  refresh  cycles.  You  can  also  try  adding  a function  that  allows 
the  user  to  enter  a color  index  and  a value,  so  that  the  user  can 
manually  change  the  color  shown  on  the  screen.  See  how  the  values 
entered  affect  the  display.  Remember  to  restore  the  original  color 
palette;  otherwise,  you  may  not  be  able  to  read  the  desktopi 


Program  BOXES 


The  program  BOXES  produces  colorful  kinetic  box  art  somewhat  like 
program  LINESl.  It  moves  a box  around  the  screen  and  the  box 
appears  to  bovmce  off  the  edges.  The  size  of  the  box  cyclically  grows 
and  shrinks.  As  each  new  box  is  drawn,  the  palette  is  rotated  to  give 
an  interesting  p^chedelic  effect 

The  program  structure  should  look  familiar  (see  Listing  6-2).  Under 
the  appllcatlon-sp>ecific  data,  variables  are  defined  to  contain  the 
lowest  and  highest  x and  y values  of  the  drawing  area  There  are  two 
16-element  arrays  to  hold  the  two  palettes:  the  rotated  palette  and  the 
original  palette.  The  variable  max-color  holds  the  maximum  number 
of  palette  entries.  If  you  run  the  program  in  the  medium  resolution 
mode,  you  must  set  this  number  to  4. 

In  the  application  functions,  the  function  Rnd-mg( ) is  the  random 
number  generator  from  an  eaiiler  program.  The  change-color( ) func- 
tion rotates  the  colors  within  the  palette.  The  draw-boxesf ) routine 
is  the  primary  function  in  the  program.  To  make  the  box  appear  to 
move  in  a straight  line  while  it  changes  size,  the  center  of  the  box  is 
used  as  the  reference  point  from  which  it  is  drawn.  Prom  the  center 
of  each  box  the  coordinates  of  its  opposite  comers  are  calculated.  The 
array  box  holds  the  comers  of  the  box,  bcx  and  bey  are  the  center  x 
and  y coordinates,  bsize  is  the  current  size  of  the  box  (in  pixels),  bdx 
emd  bcly  describe  how  the  center  coordinates  of  the  box  cire  going  to 
move,  and  bdsize  determines  how  the  size  of  the  box  will  change.  The 
cur-color  variable  is  the  current  drawing  color. 
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Listing  6-2  Program  EK)XES 

BOXES. C Draw  kinetic  box  art 

This  program  is  similar  to  LtNESl.C.  This  program  draus 
boxes  in  color  and  changes  the  color  palette  to  create 
visual  effects. 


System  Header  Tiles  & Constants 


ttlnclude 

<stdio.h 

D include 

<osblnd. 

n include 

<gemdefs 

ttlnclude 

<obdefs. 

tidefine 

FRLSE 

ttdeflne 

TRUE 

i> 

h> 

.h> 

h> 

0 

IFftLSE 


Standard  IB 
GEMDOS  routines 
GEM  flES 
GEM  constants 


GEM  Rppiication  Overhead 


Declare  global  arrays  for  VDI. 

typedsf  int  UORD; 

WORD  contrl[12), 

lntout(1283,  intln(12Bl 
ptsin[128),  ptsout(12B] 

WORD  screerL.vhandle, 

screen-phandle, 
screen_ro2, 
color^creen, 
x^ax, 
y-jnax; 


WORD  is  16  bits 
VDI  control  array 
VDI  input  arrays 
VDI  output  arrays 

virtual  screen  workstation 
physical  screen  workstation  »/ 
✓»  screen  resolution  0,1,  or  2 
flag  if  color  monitor 
max  X screen  coord 
max  y screen  coord 


Rppiication  Specific  Data 


Constant  values  for  drawing 
Int  x— lower, 
y-louer, 
x^jupper, 
y-juppar; 


area 

✓*  lowest  X value 
lowest  y value 
highest  x value 
highest  y value 


WORD  pal^ave[16), 
pal^heel[16] ; 


current  palette 
>'»  rotating  palette 


WORD  max^oior  s 16 


max  colors  displayable 
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Listing  6-2  (continued) 

6£N-related  Functions 


UORD  open^viuork(physJiandle) 

UDRD  phys^andie; 

Function:  This  Function  opens  a virtual  workstation. 

Input:  phys-Jnandle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

UORD  work^n(ll]s 

work^ut[57]  s 

nsuLJiandle;  handle  of  workstation  *y 

Int  1; 

for  (1  = 0;  1 < 10;  1++) 
work.ln[l]  = 1; 
work— ln[10]  s 2; 

newJiandle  = phys-handle;  use  currently  open  wkstatlon 

v^pnvwk(uork^n,  &nBUL-handles  woricjout); 
v^lruk(new_handle) ; clear  workstation 

r e tu  r n ( neuLJiand  1 B ) ; 

) 


set_screen^ttr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen_vhandle. 

Output;  Sets  x_max,  y-max«  color^creen«  and  screen— rez. 

{ 

UORD  worl<-jDut[57] ; 

vquBxtnd(screerL.vhandie,  0,  work-OUt) ; 

X— max  s work.jDUt[0] ; 
y-max  = workout  [1]; 

screen— TBZ  = 6etrez();  0 =5  low,  1 = med,  2 = high 

color-screen  = (screerLjrez  < 2);  mono  2,  color  0 or  1 

vq_extnd(screen— vhandle,  1,  work^jout);  got  more  Info 
y*  max.jcolor  = workjJut[4]  * work-cut(4 J y*  pianos  2 *y 
If  (maxucolor  < 2)  y*  must  have  2 colors  *y 

max— color  » 2; 

> 

Rppllcatlon  Functions 

long  RndLrng(low,  hi) 
long  low*  hi; 
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Listing  6-2  (continued) 

Function:  Generate  a random  number  betueen  low  and  hi,  inclusive. 
Input:  iou  = iouest  value  in  range. 

hi  = highest  value  in  range. 

Output:  Returns  random  number. 

< 

hi++;  include  hi  value  In  range 

return(  (Random()  (hi  - low))  + low); 

> 


changa^oior( ) 


Function:  Rotates  color  palette. 

Input:  None.  Uses  paiuwheei[]. 

Output:  None. 

Notes:  Color  index  0 is  not  changed.  Generally  you  do  not 

change  this  index  because  it  is  used  as  the 
background  color. 

{ 


register  1; 

register  NORO  temp; 


temp  = pai-uhsei[l] ; save  first  entry 

for(i  = 2;  i < max^oior;  i++)  shift  ail  entries  down  */■ 

pal-wheei[ i-1]  s pai^heei[i]; 
pal^heei[max^oior-l]  = temp;  y*  put  first  into  last 
Setpaiette(pal_wheei ) ; y*  change  palette 

return; 

> 


draw-boxes ( ) 

Function:  Do  kinetic  box  art 
Input:  None. 

Output:  None. 

{ 


^define  BOX-KRX  40 

Itdefine  BOX-NIN  4 


NORD  box[4], 
bcx,  bey, 
bsize, 
bdx,  bdy, 
bdsize; 


✓»  array  for  box  corners 
center  coords 
✓»  current  box  size 
deltas  for  box 
delta  for  size 


UfDRO  cur^olor 


>'*  current  drawing  color 
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Listiiig6-2  (contbnied) 

do  begin  screen  control  loop 

< 

v_clruk(screen_vhandle) ; clear  screen 

Initialize  line  corners 
bslze  = BOX-MIN; 

bdslze  =4; 

bcx  = RndLrngC  ( long)  (x^lower+bslze) , (long)  (x.jjpper-' bslze) ) ; 
bey  = Rnd^ngC  ( long)  (y_lower4'bslze) , ( long)  (y^pper -bslze) ) ; 
bdx  = Rnd— rng(  -10L,  10L); 

bdy  = Rnd_rng(  -10L,  10L); 

cur^olor  = 1;  start  color  Index 

y*  Box  draulng  loop  begins  here 
do 
{ 

box[0]  = bcx  - bslze;  set  corner  coords 

box[l]  = bey  - bslze; 
box[2]  = bcx  + bslze; 
box[3]  = bey  '*■  bslze; 

set  color  to  draw 

v/sf^olor(screeru.vyhandle,  cur^olor) ; 
cur_jcolor++;  set  neu  color 

If  (cur_xolor  >=  max_color) 
cur^olor  s 1; 

wr^eef  1 (screen—vhandle,  box);  Drau  box 

/*  Calculate  neu  size 
bslze  +=  bdslze; 

check  ranges 

If  (bslze  < B0XJ1IN) 

bslze  = Bax_t1IN; 
bdslze  = -bdslze; 

} 

If  (bslze  > BOX_MRX) 

{ 

bslze  = eO>CMRX; 
bdslze  = -bdslze; 

> 

/*  calculate  neu  corners 
bcx  bdx; 

bey  bdy; 

if  ((bcx  - bslze)  <=  x^ouer) 

( 


bcx  3 x^ouer  ^ bslze 
bdx  = -bdx; 
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Ustiiig6*2  (oootfanied) 

) 

if  ((hex  + bsize)  >=  x^pper) 

{ 

hex  = x^pper  - bsize; 
bdx  - -bdx; 

> 


if  ((bey  - bsize)  <»  y^ouer) 

{ 

bey  s y^auer  <f  bsize; 
bdy  = -bdy; 

> 

if  ((bey  * bsize)  >s  y-upper) 

{ 

bey  - y^ppsr  - bsize; 
bdy  s -bdy; 

> 


change  caiors 
changs-jcoior( ) ; 

} whiie  ( ICconisO  );  check  if  key  pressed 

) uhiie  ( (CraucinO  & 0x7f)  Is  27);  escape  key  exits 

return; 

> 


Main  Program 


main( ) 

( 

int  ap^d;  appiication  init  verify 

int  i; 

WORD  gr^char,  gr-hchar,  vaiues  for  VDI  handie 

gr^box,  gr_hbox; 

Initialize  GDI  Recess 


ap^d  s appi^nit(); 
if  (ap-Jld  < 0) 

{ 


Initialize  RES  routines 
no  calls  can  be  made  to  RES 
use  GEMDDS 


Cconws('***>  Initialization  Error.  <»»<>sn'); 

Cconus (" Press  any  key  to  continue. ^n* ) ; 

Craucin( ) ; 

exit(-l);  set  exit  value  to  show  error 
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Ll8tiiig6>2  (condnned) 

ecreen-phandle  = Get  handle  for  screen 

graf-handle(&gr^char,  &grjichar,  &gr^box,  &grJibox); 
screen-vhandle  = open_vwork(screen_phandle) ; 
set^creerujattrO ; Get  screen  attributes 

Application  Specific  Routines 


y*  replace  used  for  multicolors 
v8ur_moda(screenL-v/handle»  MDJ^EPLRCE) ; 

/»  set  boundaries 
x_louer  = 10; 
y_lower  = 10; 
x-jupper  = x_max  - 10; 
y-jipper  = y_jnax  - 10; 

load  palettes 

for  (1  = 0;  i < 16;  1++) 

{ 

pal^ave[l]  = SBtcolor(i,  -1); 
pal^heel[l]  = pal^ave[i]; 

> 


y*  start  program 

drauij3oxes() ; Do  box  art 

Setpalette(pal_sav;e) ; restore  palette 

Program  Clean-up  and  Exit 


v;^lsv;ul<(8creeru.vhandle) ; 
appl-Bxit( ) ; 


closB  uorkstation 
end  program 


The  flow  In  program  BOXES  Is  the  same  as  the  flow  for  program 
LINES.  An  outer  loop  initializes  the  screen  and  starting  variables.  The 
inner  loop  continual^  produces  the  kinetic  image  imtll  a kqr  is 
pressed.  The  keypress  causes  the  inner  loop  to  exit  The  outer  loop 
checks  if  the  key  was  the  ElSC  key.  If  not,  the  outer  loop  repeats  and 
a new  kinetic  image  is  produced.  If  the  ESC  kqr  was  pressed,  the 
function  diaw-boxesC ) exits  back  to  main( ) and  the  program  ends. 

In  draw-b<nes( ),  the  outer  loop  starts  by  clearing  the  screen  and 
Initializing  the  first  box.  The  variable  bsize  is  set  to  the  minimum 
box  size:  4 pixels  as  defined  in  the  program.  This  measurement 
represents  the  distance  from  the  center  to  the  edge  of  the  box  so  that 
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the  box  is  actually  8 pixels  wide  and  8 pixels  tall.  The  change  in  box 
size,  bdsize,  is  set  to  4.  The  center  x and  y coordinates  and  the  changes 
in  those  coordinates  are  randomly  selected.  The  current  color  is  set 
at  1.  The  inner  loop  now  begins. 

The  first  step  inside  this  loop  is  to  set  the  coordinates  of  the  box 
comers.  The  color  is  set  to  the  current  drawing  color  and  then 
Incremented  so  that  the  next  time  through  the  loop  a different  color 
is  used.  After  Incrementing  the  color  index,  a test  is  made  to  ensure 
that  the  color  index  is  always  less  than  or  equal  to  the  maximum 
number  of  colors  available.  Once  the  box  is  drawn,  the  new  box  size 
is  determined  and  checked  to  be  sure  it  does  not  exceed  the  size 
limits.  The  new  box  center  is  calculated  and  checked  to  see  if  the  new 
box  fits  within  the  limits  of  the  screen.  Next  the  colors  displayed  on 
the  screen  are  changed  calling  chaiige-color( ).  The  loop  ends  by 
checking  if  any  keys  have  been  pressed. 

Looking  at  the  application-speciffc  functions  of  main! ),  the  first 
instructions  are  to  set  the  writing  mode  to  replace  and  set  the 
boundaries  of  the  screen.  Note  that  the  writing  mode  XOR  is  not  used 
as  it  was  in  LINES.  When  using  color  output,  the  writing  modes  have 
a slightly  different  effect  than  in  monochrome  output  because  the 
XOR  mode  has  a strange  effect  on  the  colors;  th^r  all  come  out  the 
same!  The  replace  mode  simply  draws  over  whatever  is  on  the  screen. 
The  transparent  mode  changes  all  colors  except  the  background  color 
to  whatever  color  is  currently  set.  The  reverse  transparent  mode 
changes  only  the  backgroimd  color  to  the  current  color. 

After  the  mode  is  set,  the  palettes  are  loaded  and  dzaw-bosea( ) is 
called.  When  draw_bozes( ) returns,  the  original  palette  is  restored 
and  the  program  exits. 

Tiy  using  the  different  writing  modes  in  program  BOXEiS. 


CHAPTER  SEVEN 

Moving  Targets 


This  chapter  covers  the  VDI  concept  called  a raster  and  how  and 
where  it  is  used.  Once  you  are  familiarized  with  the  raster,  you  can 
use  it  and  many  other  VDI  features  to  create  an  ^cample  animation 
program. 


Tbe  Raster 


What  is  a raster?  A raster  is  a more  generalized  form  of  the  bit  map. 
It  is  a “rectangular”  block  of  memory  used  to  represent  a graphic 
image.  A raster,  being  rectangular,  has  a width  and  a height  The 
width  is  measured  in  two  ways:  in  pixels  that  correspond  to  in- 
dividual bits  in  memory  and  in  words.  The  viddth  must  be  a whole 
integral  of  the  word  size.  For  example,  a raster  may  be  1.  2. 3.  or  more 
words  in  width.  This  means  that  the  width  must  be  16.  32.  48.  or 
more  pixels  in  size.  The  width  in  pixds  must  be  a multiple  of  16. 
which  is  an  integral  word  size.  The  height  is  measured  strictfy  in  rows 
of  pixels.  For  color  rasters,  a third  measurement  the  number  of 
planes  is  also  used.  Look  at  Figure  7-1  to  see  how  the  raster  measure- 
ments are  made. 

Tlie  raster  is  similar  to  a screen  bit  map.  The  first  word  in  memoiy 
contains  the  first  16  bits  in  the  first  row  from  the  left  side.  The  words 
continue  across  and  down  the  raster  just  as  in  the  bit  map.  The  raster 
also  has  a coordinate  system  like  the  bit  map.  The  upper  left  comer 
is  considered  the  origin  with  a coordinate  pair  (0.0).  The  x coor- 
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Width  In  Words 


dlnates  Increase  as  you  move  from  left  to  right  and  the  y coordinates 
increase  as  you  move  from  top  to  bottom. 

Primarily,  the  raster  is  a bit  map  which  can  have  a user-specified 
size.  You  may  wonder  why  a raster  is  needed.  A raster  can  provide  a 
rsqoid  means  for  transferring  a gre^hics  image  from  one  place  in 
memoiy  to  another.  For  example,  if  you  want  to  draw  the  floppy  disk 
icon  on  the  screen,  you  can  simpfy  define  the  icon  in  a raster  and 
copy  that  image  to  any  location  on  the  screen.  This  is  much  faster 
than  redrawing  the  rectangles,  lines,  and  letters  to  the  screen  each 
time  you  want  to  display  a flopi^  disk  icon;  redrawing  could  take 
several  seconds.  Another  way  the  raster  is  used  is  to  store  a portion 
of  the  screen  in  memoiy,  use  that  area  of  the  screen,  and  then  replace 
the  original  image.  This  is  the  general  procedure  used  to  display  a 
menu  list  When  the  menu  drops  down,  the  area  under  the  menu  is 
saved  in  a raster-type  portion  of  memoiy.  When  the  user  has  finished 
the  menu  selection,  the  old  screen  image  is  copied  to  the  screen  over 
the  area  covered  by  the  menu.  Tlius,  the  screen  is  restored  to  its 
original  state. 


Using  a Raster 

You  need  two  things  to  use  a rasten  a portion  of  memoiy  to  be  used 
for  the  raster  contents  and  a Memory  Form  D^initian  Block  (MFDB). 
This  MFDB  describes  the  various  attributes  associated  with  the 
raster.  These  attributes  are  the  width  and  height  of  the  raster,  a 
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pointer  to  the  raster  location  in  memoiy.  the  number  of  planes  used 
by  the  raster,  and  a flag  telling  the  program  what  format  the  raster 
uses. 

The  Memory  Form  Definition  Block 

For  this  book's  programming  purposes,  the  MFDB  is  defined  as  a 
structure.  In  the  listing  of  the  program  RASTER  under  the  GEM 
application  overhead,  the  type  definition  for  structure  mfdbstr  con- 
tains the  necessary  elements.  There  Is  also  a structure  type  definition 
in  header  file  gemdefs.h  called  n)B.  This  is  exactly  the  same  struc- 
ture as  MFDB  in  RASTER  but  the  member  names  of  FDB  are 
abbreviated  and  not  as  ea^  to  understand. 


typedef  struct  mfdbstr 
{ 

char  »addr; 

UORO  uide; 

UORO  high; 

UDRO  uord-juidth; 
UORO  format; 

IdORO  planes; 

UORD  reservl, 
rsseru2, 
reseru3; 

} MFDB; 


The  address  is  a pointer  to  the  location  in  memoiy  where  the  raster 
resides.  Element  wide  is  the  width  of  the  raster  in  pixels;  element 
high  is  the  height  of  the  raster  in  rows  (that  is,  pixels);  and  element 
word-wldth  is  the  width  of  the  raster  in  words.  (Remember  that  the 
raster  must  have  a width  that  is  an  even  multiple  of  one  word.)  The 
element  format  determines  the  layout  of  the  raster.  If  format  is  0,  the 
layout  of  the  raster  is  in  device-specified  format  If  format  is  1,  the 
layout  is  in  standard  format  The  element  planes  determines  the 
number  of  planes  held  in  the  raster. 

Raster  Formats 

A raster  format  determines  how  the  planes  of  the  raster  are  stored  in 
memoiy.  The  VDI  uses  two  methods  for  storing  planes.  In  the  first 
method,  which  }n}u  have  already  seen,  the  first  word  of  plane  0 is 
followed  ly  the  first  word  of  plane  1 and  so  on.  This  is  known  as  an 


y*  address  of  the  raster  area 
y*  uidth  of  the  raster  in  pixels 
height  of  the  raster  in  pixels 
uidth  of  the  raster  in  uords 
standard  or  deuice-specific 
number  of  planes  in  raster 
reserved  for  future  use 
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Listing  7>1  Program  RASTER 

RASTER .C  Raster  exercising  program 

This  program  demonstrates  raster  operations.  Use  this  program 
to  experiment  uith  the  raster  operations. 


System  Header  Files  & Constants 

«»»»»«««  «««  »««»»«««  «««»»«««» «««/ 


tlinciude  <stdio.h> 
ttinciude  <osbind.h> 
tiinciude  <gemdefs.h> 
Itinciude  <obdefs.h> 


tidefine  FALSE  0 

ttdefine  TRUE  IFPLSE 


Standard  10 
6EMDQS  routines 
GEM  RES  */ 

GEM  constants 


GEM  Application  Overhead 

«««««««««««««««««««««««««««««««««««««««««««««««««»/ 


Declare  global  arrays  for  VDI.  */ 
typedef  int  MORD;  UORO  is  16  bits 

WORD  contri[12],  VDI  control  array  */ 

intout [126],  intin[120],  VDI  input  arrays  */ 
ptsin[12B],  ptscut(128];  VDI  output  arrays 


I40RD  screea-vhandie, 

8creen_phandie , 
screen_rez, 
coior^creen, 
x^ax, 
y_jnax; 

typedef  struct  mfdbstr 

{ 

char  *addr; 

UORD  uide; 

UQRD  high; 

UORD  uordUkiidth; 

UORD  format; 

UORD  planes; 

UORD  reservl,  reserv2, 

> MFDB; 


virtual  screen  uorkstation  */ 
physical  screen  uorkstation 
✓»  screen  resolution  0,1,  or  2 
flag  if  color  monitor  »/ 

/’»  max  X screen  coord 
max  y screen  coord 


/*  address  of  raster  area 
uidth  of  raster  in  pixels 
height  of  raster  in  pixels 
uidth  of  raster  in  uords 
standard  or  device  specific  */ 
number  of  planes  in  raster  */ 
reserved  for  future  use 
reservB; 


Application^ Specific  Data 
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UstiiigT'i  (continned) 

MFDB  chaxMFDB. 
strlpanFDB, 
blocknFDB, 
scrKFDB, 
tempMFDB; 

WDRD  block [16]  = < 0xFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 
0XFFFF, 


I4QRD  Qtrlp8(16]  = { 0xRRRR, 
0XRRRR, 
0XRRRR, 
0XRRRR, 
0XRRRR, 
0XRRRR, 
0xRRRR« 
0XRRRR, 
0XRRRR, 
0xRRRR« 
0XRRRR, 
0XRRRR, 
0XRRRR, 
0xRRRR« 
0XRRRR, 
0XRRRR, 


WORD  chex[32]  = { 0xCCCC,  plane  0 

0XCCCC, 

0x3333, 

0x3333, 

0XCCCC, 

0XCCCC, 

0x3333, 

0x3333, 

0XCCCC, 

0XCCCC, 
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Listing  7-1  (continued) 

0x3333, 

0x3333, 

0XCCCC, 

0XCCCC, 

0x3333, 

0x3333 

};  plane  1 will  be  set  to  0s 

WORD  temp[16) [4];  allou  for  4 planes 

GEM-related  Functions 


WORD  openL.v/uorl<(phys-handle) 

WORD  phys^andle; 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys^andle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

WORD  work.ln(Xl), 

work.jout[57] , 

neu-Jiandle;  handle  of  workstation  */ 

Int  1; 

for  (1=0;  1 < 10;  1++) 
work-ln[l]  = 1; 
work-ln[10]  = 2; 

neut-handle  = phys-handle;  use  currently  open  ukstatlon 

v^pnvwk(work_ln,  &neu_handle,  uork-jout); 
return (new_handle) ; 

> 

set.jBcr0en-jattr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen_vhandle. 

Output:  Sets  x^ax,  y-max,  color^creen,  and  screeoj-ez. 

< 

WORD  work«out[57] ; 

vq-j0xtnd(screen_vhandle,  0,  worloout); 
x^ax  = work_out[0]; 
y^ax  = workout  [1]; 

screen_rez  = 6etrez();  xif  ® = low,  1 = med,  2 = high 

color^jBcreen  = (screen_rez  < 2);  mono  2,  color  0 or  1 

} 
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f jgHng  7-1  (continiied) 

/»•«»»•»•»•»»»»•«•»»»»»»»•»•»••»•»•»«»•«»•««*»»»••« 

Rppilcatlon  Functions 

rastBr_form( ) 

Function:  Demonstrates  different  raster  formats. 

Input:  None.  Uses  global  NFDBs  and  rasters  listed  abov/e. 

Output:  Sets  fields  In  NFDBs  uhlch  should  be  reset  before 

doing  anything  else. 

{ 

Int  1; 

Checkerboard  raster 

chexMFDB.addr  = (char  *)chex; 

chexMFDB . u 1 de  = 16 ; 

chexMFDB .high  = 16 ; 

chexPlFDB.uordLuldth  = 1; 

chexNFDB. format  = 1;  standard  format 

chexMFDB. planes  = 2; 

Temporary  raster  area 

tempMFDB.addr  = (char  *)temp; 

tempMFDB.ulde  = 16; 

tempMFDB.hlgh  = 16; 

tempMFDB.uorcLj«ildth  = 1; 

tempMFDB. format  = 0;  ulll  be  set  by  vr_trnfmn 

tempMFDB. planes  s 2;  must  be  same  as  source 

v/r_trnfm(screen.vhandle,  &chexMFDB«  &tempMFDB); 
prlntf( "Transform  from  Standard  to  Deulce-speclf ic^n" ) ; 
for  (1  = 0;  1 < 32;  1++) 

printf  ( "!t2d:  Standard  %6x  Deulce  %6x^n", 

1,  chex[l]«  temp[l]); 

Craucln( ) ; 

chexMFDB. format  = 0;  set  to  device-specific 

vr_trnfm(screerL.vhandle,  &chexMFDB,  &tempMFDB); 
prlntf( "Transform  form  Device-specific  to  Standard^n” ) ; 
for  (1  = 0;  1 < 32;  1++) 

prlntf(*%2d:  Device  XGx  Standard  )i;6x\n”« 

1,  chex[l],  temp[l]); 

Craucln( ) ; 

> 

SBt,.up-rasters( ) 

Function:  Sets  up  global  MFDBs  to  point  to  rasters. 

Input:  None.  Uses  global  MFDBs  and  rasters  listed  above. 

Output:  Sets  appropriate  fields  in  MFDBs. 

< 
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Listing  7-1  (continaed) 

Checkerboard  raster 
chexUrOB.addr  = 

chexiirOB.ulde  = 

chexKFOB.high  = 

chexKFDB.word-uldth  = 
chexMFDB. format  = 

chexMFDB. planes  = 


(char  »)chex; 

IG; 

16; 

1; 

0;  must  be  deulce-speclf ic 

1;  monochrome  has  1 plane 


Stripe  raster 
strlpeMFOB.addr 
strlpehFDB.ulde 
s t r IpeilFDB . h 1 gh 
strlpehFDB.uorGUMldth 
strlpehFDB. format 
strlpeMFDB. planes 


Block  raster 

blockhFOB.addr  s (char  *)block; 

blockMFOB.ulde  = 16; 

blockKFOB.hlgh  = 16; 

blocktlFDB.uordjuldth  = 1; 

blockMFDB. format  = 0; 

blockllFDB. planes  = 1;  monochrome  has  1 plane 


Screen  raster  area 

scrttFDB.addr  = (char  *)Logbase(); 

scrKFDB.ulde  ^ G40; 

scrllFDB.hlgh  = 400; 

scrltFDB.uordLuldth  s 40; 

scrttFOB • forma  t = 0 ; 

scrilFDB. planes  =1;  monochrome  has  1 plans 

If  (scresrL^ez  ==  0)  lou  resolution 

< 

scrilFDB.  ulde  = 320; 

scrttFDB-hlgh  = 200; 

scrilFDB.uord-uldth  = 20; 
sc rMFDB. planes  = 4; 

i 

else  If  (screen^ez  ==  1)  medium  resolution 

< 

scrllFDB.hlgh  = 200; 

scrilFDB.  planes  = 2; 

> 


Temporary  raster  area 

tempnFDB.addr  = (char  *)temp; 

tempMFDB.uide  = 16; 

tempIlFDB.hlgh  = 16; 

tempNFDB.uordjuildth  = 1; 

temphFDB. format  = 0; 

tempMFDB. planes  = scrMFDB .planes;  same  as  screen 

} 
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Ustiiig?-!  (continued) 

raster^testn 

Tunctlon:  Draw  patterns  using  rasters. 

Input:  None.  Uses  tlFDBs  and  rasters  defined  above. 

Output:  None.  No  changes  to  MFDBs  and  rasters  except  temp. 

< 

UORD  pxy[8], 

color_lndex[2] ; 
int  pass; 

color„index[0]  = 1; 
color.index[l]  » 0; 


For  (pass  » 0;  pass  <2;  pass++) 

{ 

v-cl  ruk  ( screerL.vhandl  e ) ; 
vsf^nterior(screerL..vhandlB,  2); 
vsf^tyle(screerL.vhandls,  2); 
pxy[0]  = pxy[l]  = 10; 
pxy(2)  = pxy(3)  = 150; 
vr_recf 1 (screen—vhandle,  pxy ) ; 


use  to  loop  tulce 

Foreground  color  value 
Background  color  value  */ 

first  pass  uses  vrt.jcpyfm 
/■»  second  pass  uses  vra_cpyfm 
/*  set  background  pattern 


Save  portion  of  screen  In  temp 


pxy[0]  = 100; 
pxy[l)  = 100; 
pxy[2]  = 115; 
pxy(3]  = 115; 
pxy(4)  = 0; 
pxy(5)  = 0; 
pxy(6]  = 15; 
pxypj  = 15; 


/■»  source  xl  coord 
source  yl  coord 
/»  source  x2  coord 
source  y2  coord 
dest  xl  coord 
dest  yl  coord 
✓»  dest  x2  coord 
dest  y2  coord 


vro^pyfm(screen-.vhandle*  S.JDNLY,  pxy, 
&scrriFDB,  &tempnFDB); 


Drau  checkerboard  pattern  In  saved  area 
pxy[0)  = pxy[l]  = 0; 

pxy[2)  = pxy[3]  = 15; 

pxy(4]  = pxy[5]  = 100; 

pxy(6]  = pxy(7]  = 115; 

if  (pass) 

vro^pyfm(screerLJvhandle,  SJONLY,  pxy, 
&chexMFDB,  &scrHF0B) ; 

else 

vrt.jcpyfm(screerL.vhandle,  ND.J9EPLBCE,  pxy, 
&chexNFD8,  IscrNFOB,  color^ndex); 


Craucln( ) 
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Listing  7*1  (continued) 

Drau  stripe  pattern  ov;er  part  of  checkerboard 
pxy(0]  = pxy[l]  = 0; 

pxy[2]  = pxy[3]  = 15; 

pxy[4]  = pxy[SJ  = 110; 

pxy[6]  = pxy[7]  = 125; 

If  (pass) 

wro-jcpyfm(scre8ruwhandle,  SJDNLY,  pxy, 

&8trlpenFDB,  &8crnFDB); 

else 

v/rt^pyf(n(screen_vhandle,  MO_REPLRCE,  pxy, 

&strlpenFDB,  &scrMFDB,  color^ndex); 

Crai4cln( ) ; 

Draw  block  pattern 

pxy(0)  = pxy(l)  = 0; 

pxy(2)  = pxy(3)  = 15; 

pxy(4)  = pxy(5)  = 132; 

pxy(6]  = pxy(7)  = 147; 

If  (pass) 

vro_cpyf(n(8creen_vhandle,  SJDNLY,  pxy, 

&blockMFDB,  &scrnFDB); 

else 

vrLjcpyf(n(screen^vhandlB,  t1D_REPLRCE,  pxy, 

&blockMFDB,  &8crMFDB,  color^ndex); 

Craucln( ) ; 

Demonstrate  different  rectangle  sizes  with  block  pattern 

pxy(0]  = pxy[l]  =0;  destination  wider  than  source 

pxy(2]  = pxy[3]  = 10; 

pxy(4]  = pxy[S]  = 10; 

pxy(6]  = S0; 

pxy(7]  = 20; 

If  (pass) 

vro^pyfm(8creen_vhandlB,  SJDNLY,  pxy, 

&blockHFDB,  &BcrNFDB); 

else 

vrt^pyfm(scr88n_vhandle,  MD—REPLRCE,  pxy, 

&blockhFD5,  &scrt1FDB,  color_lndex) ; 

Crawcln( ); 

pxy[0]  = pxy[l]  =0;  destination  longer  than  source 

pxy(2)  = pxy(3)  = 10; 

pxy(4)  = 60; 

pxy[5]  = 10; 

pxy(6]  = 70; 

pxy[^l  = 50; 

If  (pass) 

uro-cpyfm(screBn.uhandle,  SJDNLY,  pxy, 

&blackNFDB,  &scr(1FDB); 

else 

urt^pyfm(8crBBn_vhandle,  MD-REPLRCE,  pxy, 

&blockNFDB,  &8crMFD5,  color^lndex) ; 


Crawcln( ) 
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UstingT-l  (oontinned) 

Replace  sashed  portion  of  screen  from  temp 
pxy[0]  = pxy[l]  = 0; 
pxy[2]  = pxy[3]  = IS; 
pxy[4]  = pxy[S]  = 100; 
pxy[G]  = pxy[?]  = IIS; 
vra^pyfm(8creen.syhandle,  S_DNLY,  pxy, 
&tempMFDB,  iecrMFDB); 

Craucln( ); 

} end  pass  loop 


color_test( ) 

Function:  Shou  use  of  raster  copy  and  ur 1 ting  modes  with  color. 
Input:  None.  Uses  chex[],  chexKFDB,  and  scrKFDB. 

Output:  None. 

{ 

UORO  pxy[B], 

color_lndex[2] ; 


v.jclruk(8creerL.vhandle) ; 
pxy(0]  = 10;  pxy[l)  = 10; 

pxy[2]  s 300;  pxy[3]  = 150; 
usf— lnterior(screenL.v/handle,  1); 
usf.jcolor(screerL.vhandle,  4); 
ur^Bcf  1 (screerL-vhandle,  pxy); 


clear  screen 


solid  fill 

use  color  4 to  fill  »/ 
y*  draw  rectangle  *>' 


y*  use  replace  mode  *y 

pxy[0]  = 0;  pxy[l]  = 0; 


pxy[2]  = 15 
pxy[4]  = 50 
pxy[G]  = 65 
if  [color^creen) 
< 


pxy(3]  = 15 
pxy[5]  = 20 
pxy[7]  = 35 


color— index[0]  = 2; 
color— lndex[l]  = 3; 

> 

else 

< 

color— index[0]  = 1; 
color— lndex(l]  = 0; 

> 

vr  t.jcpy  f m ( screen— uhandle , 
&chexKFDB,  &scrKF0B, 


y*  color  for  1 bits  *y 
y*  color  for  0 bits  *y 


KD— REPLRCE , pxy , 
color— Index); 


y*  use  transparent  mode  ^y 

pxy[4)  = 100;  pxy[5)  = 20; 
pxy[6]  = 115;  pxy[7)  = 35; 
vrt— cpyfm( screen— vhandle,  NO— TRRN5,  pxy, 
&chexNFDB,  &6crNFDB,  color— Index) ; 


I 
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Uatliig7-1  (contlntied) 

use  XGR  mode 

pxy[4]  = 150;  pxy[S]  = 20; 
pxy[6]  = 165;  pxy[7]  = 35; 
v/rt_cpyf(n[sc:reen_v/handle,  MO^OR,  pxy, 
&chexMFDB,  &5crMFDB,  color^ndex); 

use  reuerse  transparent  mode 
pxy[4)  = 200;  pxy[S]  = 20; 
pxy[6]  = 215;  pxy[7]  = 35; 
vrt_cpyfm(8creea.v/handle,  M0-ERRS6,  pxy, 
&chexMF0B,  &BcrMFDB,  coior_index] ; 

return; 

> 


Main  Program 


main( ) 

{ 

int  ap— id; 

WORD  gr-uchar,  gr_hchar. 

✓» 

gr_bibox,  grJibox; 


application  Inlt  verify 
values  for  VDI  handle 


Initialize  GEM  Recess 


ap^d  = appi-lnlt();  Initialize  RES  routines 

if  (ap^d  < 0)  no  calls  can  be  made  to  RES 

{ USB  GEMDOS 

Cconus( ■***>  Initialization  Error.  <*»*vn"); 

Cconus( 'Press  any  key  to  continue. ^n' ) ; 

Craucin( ) ; 

exit('l);  set  exit  value  to  show  error 

} 

BcreerL43handle  = Get  handle  for  screen 

graf-handie(&gr^char,  &gr^char,  &gr^box,  &gr_hbox]; 
screerL-vhandie  = open— vuork(6creen-phandle) ; 
set^jBcreen-attrO ; Get  screen  attributes 


Rpplication  Specific  Routines 


v_c 1 ruk ( screen— vhandl e ) 
raster— form( ) ; 
set^p-rastersQ ; 


y*  clear  uorkstation  *y 
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Listing  7-1  (continued) 

raster_test( ) ; 
color_test( ) ; 

/******»***»»*#******»♦«»«*****»******************** 

Program  Clean-up  and  Exit 

******************************************  it********/ 

Walt  for  l<eyboard  before  exiting  program 

Craucin();  GEMDOS  character  input 

v^isv^wl<(screen_uhandle) ; /*  close  workstation 

appi_£xit();  end  program  */ 

> 

/»«««««««•»««««»*»••••««»«• v******^****^****^******^/ 


interleaved  format,  which  the  VDI  has  termed  the  device-specific 
format  (see  Figure  7-2).  The  second  format  has  all  the  words  for  plane 
0 set  consecutively  in  memory.  This  is  followed  by  all  the  words  for 
plane  1 . all  the  words  for  plane  2.  and  so  on  until  all  planes  have  been 
listed.  This  is  a contiguous  format  and  is  called  the  standcmd  format 
in  the  VDI  (see  Figure  7-3). 

Memory 
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Memory 


Figure  7-3  Standard  Format  Plane  Layout 


The  device-specific  format  is  said  to  be  device-specific  because  this 
format  may  be  different  on  another  computer  system.  The  format 
shown  here  is  the  one  used  on  the  Atari  ST.  Also  note  that  a 
monochrome  (monoplane)  raster  is  the  same  in  either  device-specific 
or  standard  format.  The  program  RASTER  will  demonstrate  the  dif- 
ference between  standard  and  device-specific  formats  and  how  to  use 
a transformation  function  that  can  convert  from  standard  to  device- 
specific format  and  vice  versa. 
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Color 


The  Implementation  of  color  in  a raster  is  the  same  as  in  the  screen 
bit  map.  Each  plane  contributes  one  bit  toward  an  index  in  the  VDI 
color  tabte  for  that  particular  pixel  The  default  color  indices  are  listed 
in  Table  7-1. 


Table  7-1:  Pixel  Value  to 
Color  Index  Mapping 


Pixel  Value 

Color  Index 

0000 

0 

0001 

2 

0010 

3 

0011 

6 

0100 

4 

0101 

7 

0110 

5 

0111 

8 

1000 

9 

1001 

10 

1010 

11 

1011 

14 

1100 

12 

1101 

15 

1110 

13 

1111 

1 

Using  tile  Rasters  in  a Program 

To  use  a raster  in  a program,  you  must  set  up  the  raster  and  its 
MFDB.  You  must  also  use  one  of  the  two  raster  cop}dng  functions  to 
get  the  image  to  show  on  the  screen.  Essentially  you  are  copying  the 
raster  from  its  original  location  to  the  screen  raster  (bit  map),  llie 
first  copying  function  is  called  an  opaque  raster  copy.  Tlie  second  is 
a transparent  raster  copy.  The  opaque  copy  function  transfers  the 
image  from  a source  raster  to  a destination  raster  pixel  for  pixel 
Thus,  it  overwrites  the  destination  raster  with  the  somee  raster.  The 
overwriting  result  is  governed  by  the  writing  mode  used  for  the  copy 
function. 

Opaque  Copy  Raster  Function 

The  opaque  copy  raster  function  is  called  from  a C program  as  follows: 

vro-cpyfinfhandle,  wr_mode,  lu^anay.  psrcBlFDB,  pdesBSFDB) 
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The  parameters  in  the  opaque  copy  function  start  with  the  worksta- 
tion handle.  This  parameter  does  not  have  any  effect  on  the  raster 
copy  but  is  includ^  for  consistency  with  all  other  VDI  function  calls. 
Tlie  second  parameter  is  the  writing  mode,  which  determines  how  the 
raster  is  copied.  The  third  parameter  is  an  array  describing  the  area 
to  copy  from  and  the  area  to  copy  to.  The  last  two  parameters  of  the 
function  are  the  addresses  of  the  source  MFDB  and  the  destination 
MFDB,  respectively. 

There  are  16  different  copy  modes  that  perform  a variety  of  logic 
operations  between  the  soiuce  bit  and  destination  bit  Table  7-2 
shows  the  logic  operation  associated  with  each  mode.  In  the  table,  “S” 
stands  for  the  source  bit  and  "D"  stands  for  the  destination  bit  The 
result  of  the  operation  is  placed  in  the  destination  raster.  Several 
modes  are  wor^  special  note.  Mode  0 is  the  clear  mode.  It  turns  all 
bits  in  the  destination  raster  to  0.  Mode  3 is  the  replace  mode,  which 
exactly  copies  the  contents  of  the  source  raster  into  the  contents  of 
the  destination  raster  without  regard  to  the  contents  of  the  destina- 
tion raster.  Mode  4 maps  the  destination  bits  to  1 if  the  source  bit 
has  a value  of  0 and  the  destination  bit  has  a value  of  1;  otherwise, 
the  destination  bit  is  set  to  0.  Mode  5 leaves  the  destination  raster 
unchanged.  Mode  10  Inverts  the  existing  destination  raster.  Mode  12 
inverts  the  source  raster.  Mode  15  sets  all  bits  in  the  destination 
raster  to  1.  Cleaity,  the  writing  mode  is  very  significant  Since  the 
opaque  copy  makes  copies  pixel  pixel  changing  the  writing  mode 
can  produce  some  rather  interesting  results,  such  as  changing  the 
color  of  the  image  (when  working  with  planes)  or  changing  the  image 
Itself. 


Table  7-2:  Opaque  Raster  Coi^ 
Logic  Operations 


Mode 

Operation 

Mode 

Opemtlon 

0 

set  to  0 

8 

~(S  1 D) 

1 

S&D 

9 

~(S  ’ D) 

8 

S&-D 

10 

~D 

3 

S 

11 

S 1 ~D 

4 

-S&D 

12 

~S 

5 

D 

13 

~S  1 D 

6 

S * D 

14 

- (S  & D) 

7 

S 1 D 

15 

set  to  1 

The  third  parameter  of  VTO-cpyfm( ) is  an  array  that  holds  the 
coordinates  of  two  rectangles.  The  first  four  elements  locate  a rectan- 
gular area  within  the  sotuce  raster.  This  denotes  the  area  from  which 
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the  pixels  are  copied,  and  allows  you  to  copy  all  or  only  part  of  a raster. 
The  last  four  elements  of  the  array  outline  a rectangular  area  in  the 
destination  raster  where  the  source  pixels  are  to  be  copied.  \Wth  this 
option,  you  may  locate  your  raster  image  an)where  within  the  des- 
tination raster.  In  the  earlier  example  of  copying  a floppy  disk  icon  to 
the  screen,  the  destination  raster  (the  screen)  is  obviously  much 
bi^er  than  the  source  raster.  By  specifying  the  coordinates  of  the 
rectangular  area  in  the  destination  raster,  you  can  map  the  icon 
anywhere  on  the  screen. 

Note  that  since  the  source  and  destination  rasters  may  be  the  same 
(for  example,  cop3ring  from  one  portion  of  the  screen  to  another),  you 
may  wind  up  in  a situation  where  the  source  and  destination  rec- 
tangles ovetlap.  This  situation  has  been  accounted  for  by  the  VDI  so 
that  you  don’t  wind  up  changing  a portion  of  the  source  raster  before 
it  has  been  copied.  The  VDI  guarantees  that  any  area  in  the  source 
raster  is  not  changed  until  it  has  been  copied  to  the  destination 
raster.  In  other  words,  the  source  raster  is  not  “drawn  over"  until  the 
corresponding  area  in  the  destination  raster  has  alr^dy  been  copied. 

A few  other  notes  about  the  opaque  copy  function.  The  opaque 
raster  copy  function  does  not  perform  any  transformations  or  rota- 
tions. Thus,  if  you  have  a source  raster  in  device-specific  format  the 
destination  raster  must  also  be  in  device-specific  format  Also,  all 
copying  is  done  strictly  pixel  by  pixel  Finally,  if  the  source  and 
destination  rectangles  are  not  the  same  si^,  the  VDI  manual  states 
that  the  VDI  uses  the  destination  for  a pointer  and  the  source 
rectangle  for  the  resulting  size.  In  program  RASTER,  the  results  of 
this  operation  are  seen.  It  is  left  to  the  reader  to  determine  how  weU 
this  option  works.  On  the  author’s  version  of  GEM,  this  feature  was 
apparently  not  working  propeify. 

Transparent  Copy  Raster  Function 

The  other  copy  function,  transparent  copy  raster,  is  used  to  create  a 
color  image  from  a monochrome  raster.  The  function  call  from  a C 
program  is  as  follows: 

vrt-cpyfinfliandle,  wr-mode,  piyanay. 
psrcMFDB,  pdesBOFDB,  color  Jndex) 

The  parameters  are  similar  to  the  opaque  copy  function.  The  first 
parameter  is  the  workstation  handle.  The  second  parameter  is  the 
writing  mode.  The  third  parameter  is  the  source  and  destination 
rectangle  array.  The  next  two  parameters  are  pointers  to  the  source 
and  destination  MFDBs,  respectively.  The  last  parameter  is  a two-ele- 
ment array  that  determines  the  color  output 

The  writing  mode  for  the  transparent  copy  is  different  from  the 
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writing  mode  for  the  opaque  copy  function.  The  writing  modes  are 
the  same  used  for  standard  VDI  functions:  replace,  transparent;  XOR. 
and  reverse  transparent  These  modes  are  used  in  conjunction  with 
the  color  index  array  to  produce  color  output  Color  index  array 
element  0 is  used  to  determine  the  color  of  the  foreground,  and 
element  1 is  used  to  determine  the  backgroimd  color.  The  value  of 
the  array  element  is  the  color  index  in  the  VDI  color  table. 

In  replace  mode,  all  pixels  with  a value  of  1 in  the  source  raster 
yield  a pixel  with  color  color_indexIO]  in  the  destination,  and  all 
pixels  with  a 0 value  have  color  color-indes(l]  at  the  destination.  In 
transparent  mode,  a 1 bit  in  the  source  produces  a pixel  of 
color_lndex[0]  in  the  destination.  Source  bits  with  a 0 value  have  no 
effect  on  the  destination  pixel.  In  XOR  mode,  an  XOR  operation  is 
performed  between  each  pixel  of  the  source  raster  and  each  bit  in 
each  of  the  destination  planes.  The  color  index  array  is  not  used 
at  all  with  this  mode.  Reverse  transparent  mode  is  the  reverse  of 
transparent  mode;  wherever  the  source  raster  has  a pixel  set  to  0. 
color-indez[l]  is  output  to  the  destination.  Source  pixels  set  to  1 
have  no  effect  on  the  destination. 

Raster  Conversion 

To  convert  a raster  from  device-specific  format  to  standard  format  (or 
vice-versa).  VDI  provides  a transform  form  function: 

VT-tni£m(]iandle,  psrcMIDB,  pdesIlFBB) 

The  parameters  are  the  workstation  handle,  the  address  of  the  source 
MFDB.  and  the  address  of  the  destination  MFDB.  The  values  held  in 
the  source  MFDB  determine  how  the  function  operates.  The  source 
MFDB  contains  the  number  of  planes  to  be  transformed  and  the 
format  to  be  used  for  the  destination.  If  the  source  raster  is  In 
standard  format,  the  destination  is  converted  to  device-specific  for- 
mat; otherwise,  the  destination  is  converted  to  standard  format  The 
destination  MFDB  has  its  format  field  set  to  the  resulting  format  by 
the  transform  function,  but  all  other  parameters  of  the  destination 
MFDB  must  be  manually  set  before  the  function  call  because  they  are 
not  altered. 


Program  RASTER 

Program  RASTER  demonstrates  the  use  of  rasters  and  raster  copy 
functions.  In  the  GEM-appllcation  overhead  in  Listing  7-1.  there  is 
the  usual  overhead  plus  the  type  definition  for  the  MFDB.  As  men- 
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tioned  earlier,  our  own  structure  is  used  because  it  is  much  easier  to 
read  and  understand  than  the  one  included  in  the  GEM  header  file 
gemdefs.h. 

Under  the  application-specific  data,  there  are  five  different  MFDBs 
defined.  This  program  demonstrates  how  to  create  and  copy  raster 
images  and  the  effects  of  various  copying  and  writing  modes.  There 
are  three  defined  rasters;  a checkerboard,  a stripe,  and  a solid  block. 
The  other  two  MFDBs  are  used  for  the  screen  and  for  temporary 
storage  of  screen  contents,  respectively. 

Four  arrays  are  used  to  hold  the  raster  images.  The  block  and  stripe 
rasters  are  16-by-16  pixels.  The  checkerboard  raster  contains  two 
planes  of  that  size.  Therefore,  the  array  to  hold  the  block  and  stripe 
patterns  is  16  words  long  because  the  rasters  are  16  pixels  (1  word) 
wide  by  16  pixels  high.  The  array  to  hold  the  checkerboard  raster  is 
32  words  long  (2  planes  of  16  rows  each).  The  temporary  raster  must 
be  able  to  hold  four  planes  so  that  it  can  store  low  resolution  color 
images  from  the  screen.  The  numbers  used  to  initialize  the  arrays 
represent  the  raster  images  held  by  arra}^.  The  process  for  converting 
from  a pixel  image  to  a hexadecimal  v^ue  is  shown  in  Figures  7-4 
through  7-6. 
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Figure  7-4  Block  Pattern 
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1111 
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1111  1111  1 1 1 1 -♦  FFFF 
1111  1111  1111  FFFF 
1111  1111  1 1 1 1 -»  FFFF 


In  these  figures,  the  three  different  rasters  have  been  drawn  in 
16-by-16  grids.  The  block  pattern  consists  of  filling  in  every  bit.  The 
stripe  pattern  consists  of  vertical  lines,  and  the  checkerboard  pattern 
is  a checkerbozird.  Since  C does  not  have  binary  constants,  you  need 
to  represent  the  bit  images  in  either  decimal,  octal,  or  hexadecimal 
numbers.  The  easiest  conversion  is  to  hexadecimal  numbers.  To  do 
this,  the  “on”  bits  of  the  image  are  given  a value  of  1 and  the  “off" 
bits  a value  of  0.  Each  row  in  the  image  is  divided  into  4-blt  groups, 
and  each  4-blt  group  is  converted  into  its  hexadecimal  code.  This 
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1 100  1 100  1 100  1 100  CCCC 
1100  1100  1100  1100 CCCC 
001 1 001 1 001 1 001 1 3333 
001 1 001 1 001 1 001 1 3333 

1100  1100  1100  1100 -»  CCCC 


Figure  7-6  Checkerboard  Pattern 


transformation  from  pixels  to  bits  to  hexadecimal  is  shown  in  each 
of  the  figures.  For  each  array  element  then,  simply  fill  in  the  8^)- 
propriate  hexadecimal  value.  Notice  that  the  checkerboard  array, 
which  is  supposed  to  hold  32  elements,  has  only  16  elements  defined 
(representing  one  plane  out  of  a possible  two).  The  remaining  ele- 
ments are  automatical^  set  to  0 by  the  C compiler. 

In  main( ).  the  program  performs  the  usual  initialization  and  clears 
the  workstation.  Four  application  routines  are  then  called.  The  first 
raster_ibim( ).  demonstrates  the  differences  between  the  standard 
raster  format  and  the  device-specific  format.  The  routine 
Bet-iq>-xa8tiers( ) initializes  all  the  MFDBs  used  in  the  program.  The 
third  function,  Taster_test( ),  provides  a comparison  between  the 
opaque  and  transparent  raster  copy  functions  and  an  outline  for  the 
user  to  experiment  with  these  copy  functions.  The  final  function. 
color_test(),  shows  how  the  different  writing  modes  affect  the 
transparent  copy  raster  function. 
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The  routine  ra8ter-fonii( ) uses  the  checkerboard  raster  to  go  be- 
tween the  standard  format  and  the  devlce-speclflc  format  This  func- 
tion first  sets  up  the  MFDBs.  The  variable  chexMFDB  is  set  to  point 
to  the  start  of  the  chex  array,  which  holds  the  checkerboard  image 
raster.  Its  width  and  height  are  16  pixels,  the  word  width  is  1.  and 
the  format  is  set  to  the  standard  format  denoted  the  value  1.  For 
this  test  the  program  uses  the  two  planes  of  the  checkerboard  raster. 
The  temporary  raster  MFDB  is  set  up  with  the  same  attributes  except 
that  it  points  to  the  temporary  array.  The  vr_tmfin( ) function  takes 
the  raster  pointed  at  by  chedHTOB  and  places  it  into  the  raster 
pointed  at  tempMFDB.  The  32  elements  (rows)  of  the  chez  and 
temp  arrays  are  then  printed  out  to  show  the  difference  between  the 
standard  and  device-specific  format  of  the  two  rasters.  Note  that  the 
numbers  in  the  piintit ) statements  are  printed  in  hexadecimal  nota- 
tion so  thQT  can  easily  ^ compared  to  their  initial  settings  at  the  top 
of  the  program. 
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Figure?-?  Tnuisfoiiiiiiig  a Raster  from  Standard  to  Device-Spedflc  Format 

The  transformation  occurs  as  shown  in  Figure  7-7.  The  transfor- 
mation involves  taking  the  contiguous  words  in  discrete  planes  (stan- 
dard format)  and  converting  them  into  interleaved  planes  (device- 
specific format).  The  chex  array  starts  in  standard  format  with  all 
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words  of  plane  0 coming  first,  followed  by  all  words  for  plane  1.  The 
temp  array  holds  the  checkerboard  pattern  in  device-specific  format 
with  word  0 of  plane  0,  followed  by  word  0 of  plane  0,  then  word  1 of 
plane  0,  and  so  on. 

After  printing  the  results  of  this  first  transformation,  function 
raster_fonn( ) waits  for  the  user  to  press  a key  and  then  performs  the 
opposite  transformation.  The  format  field  of  chexMFDB  is  set  to 
indicate  that  the  cfaes  raster  is  in  device-specific  format  Although  the 
actual  data  has  not  been  changed,  you  are  telling  the  VDI  that  the 
data  is  in  device-specific  format  The  transformation  function  is  called 
to  convert  the  raster  from  device-specific  format  to  standard  format 
The  results  are  shown  in  Figure  7-8. 
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Flgnie  7-8  Ttansfonniiig  a Raster  from  Device-Specific  to  Standard  Format 

Remember  that  the  Atari  ST  screen  bit  map  uses  the  device-specific 
format  If  you  do  any  copying  to  and  from  the  screen,  be  sure  to  set 
the  format  field  of  the  MFDB  properly. 

After  the  raster  transformations  have  been  demonstrated,  the 
8et_«qp_rasteis( ) function  is  called  next  This  function  sets  up  the 
~MFDBs  for  the  checkerboard,  stripe,  and  block  rasters  to  be  used 
by  the  other  functions  in  this  program.  The  addresses,  width,  height 
format  and  number  of  planes  are  set  for  each  MFDB.  Note  in 
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chedMFDB  that  only  one  plane  is  being  used  at  this  time.  The  pro- 
gram simply  ignores  the  second  plane.  Its  only  purpose  is  demonstrat- 
ing the  transformations. 

Next  the  structure  screenBIFDB  is  set  up.  The  address  of  the  raster 
(bit  map)  is  obtained  using  the  Logbase( ) function,  as  it  was  in 
the  BITMAP  program.  The  width  and  height  are  initially  set  to  the 
number  of  pixels  on  a high  resolution  monochrome  monitor,  and  the 
number  of  planes  is  set  to  one.  The  screen  resolution  is  tested:  the 
variable  screen_jez  is  set  in  8et-screen_attr( ).  If  it  is  0,  a low  resolu- 
tion screen  is  being  used  and  the  width,  height,  word  width,  and 
number  of  planes  are  set  appropriately.  If  a medium  resolution  screen 
is  being  used,  the  width,  height  and  number  of  planes  are  changed. 
The  word  width  does  not  need  to  be  reset  under  medium  resolution 
because  it  is  the  same  as  for  high  resolution. 

Finedly,  the  temporaiy  MFDB,  temfAIFDB,  is  set  up.  The  device- 
specific format  is  used.  The  number  of  planes  is  set  to  the  same 
number  of  planes  used  by  the  screen  because  the  temporaiy  raster 
will  store  a portion  of  the  screen.  Now  that  all  of  the  MFDBs  have 
been  set  the  raster  test  function  can  be  performed. 

In  raster_test( ),  the  pay  array  holds  die  coordinates  of  the  source 
and  destination  rectangles.  The  color-index  array  is  used  for  the 
transparent  copy  raster  function.  The  variable  pass  is  used  to  loop 
through  the  function  twice.  The  first  time  the  transparent  copy  raster 
function  is  used;  the  second  time  the  opaque  copy  raster  function  is 
used. 

The  function  begins  by  setting  the  two  color-index  array  elements 
to  the  foreground  color  (black)  and  the  background  color  (white). 
Inside  the  loop,  the  workstation  is  cleared.  A background  pattern  is 
drawn  by  setting  the  interior  fill  mode  to  pattern  fill  using  pattern 
number  2.  Then  a filled  rectangle  is  drawn  from  coordinates  (10,10) 
to  (150,150). 

The  function  continues  by  preparing  the  psy  array  to  store  a por- 
tion of  the  screen  into  the  temporaiy  raster.  A 16-by-16  pixel  square 
will  be  stored  from  coordinates  (100,100)  to  (1 15,1 15).  This  square  is 
placed  in  the  temporaiy  raster  from  location  (0,0)  to  (15,15).  Remem- 
ber that  the  first  coordinate  of  the  raster,  (0,0),  is  at  the  upper  left 
comer  of  the  raster.  When  saving  a portion  of  the  screen,  the  opaque 
copy  raster  function  must  be  used  because  the  transparent  copy 
raster  function  is  only  for  use  with  a monochrome  source  raster  and 
a color  destination  raster.  Since  you  do  not  know  whether  your 
program  runs  on  a intern  with  a monochrome  or  color  screen,  it  is 
easiest  to  use  the  opaque  copy  raster  function.  In  this  way,  if  the 
screen  has  one,  two,  or  four  planes,  the  opaque  copy  is  able  to  handle 
it  The  opaque  copy  raster  function  is  used  to  copy  pixel  for  pixel  from 
the  screen  to  the  temporaiy  raster  area.  Notice  that  the  second 
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parameter  is  the  defined  constant  S-ONLY.  This  constant,  the  other 
15  logical  writing  modes  for  opaque  copies,  and  the  four  writing 
modes  used  by  the  VDI  are  defined  in  the  header  file  obdefs.h.  The 
use  of  these  constants  is  strongly  recommended  because  they  make 
the  program  much  easier  to  understand. 

At  this  point  a 16-by-16  square  has  been  copied  from  the  screen 
into  the  temporary  raster  area.  Now  the  checkerboard  pattern  is 
drawn  into  the  area  on  the  screen  Just  saved.  To  do  this,  the  coor- 
dinates in  the  psy  array  are  reversed  because  the  program  is  copying 
the  image  from  the  checkerboard  raster  to  the  screen.  Since  the  whole 
checkerboard  raster  is  copied,  the  coordinates  are  from  (0,0)  to 
(15,15).  The  raster  is  placed  on  the  screen  at  screen  coordinates 
(100,100)  to  (115,115).  On  the  first  pass  through  the  loop,  the 
transparent  copy  raster  function  with  replace  mode  is  used.  The 
program  pauses  and  waits  for  a k^r  to  be  pressed.  Then  the  stripe 
pattern  is  drawn  overl£q>ping  the  checkerboard  pattern  sli^tty.  The 
block  pattern  is  then  drawn  on  the  screen  at  another  location. 

After  another  key  press,  the  use  of  different  source  and  destination 
rectangle  sizes  is  demonstrated.  A lO-by-10  pixel  square  is  taken  from 
the  block  raster  and  placed  on  the  screen  in  a rectangle  40  pixels  wide 
and  10  pixels  high.  Next  the  block  raster  is  placed  on  the  screen  in 
a lO-ly-40  pixel  rectan^e. 

At  the  end  of  the  loop  after  a key  press,  the  program  restores  the 
portion  of  the  screen  saved  earlier.  The  opaque  copy  raster  function 
is  used  to  replace  that  area  of  the  screen  pixel  for  pixel.  A pattern  was 
placed  on  the  screen  earlier  to  enable  you  to  see  that  the  image  is  ac- 
tually being  replaced.  If  a white  background  were  used,  the  program 
would  look  pretty  dull. 

On  the  second  pass  through  the  loop,  the  opaque  copy  raster 
function  is  used  instead  of  the  transparent  copy  raster  function. 
There  is  a difference  between  using  one  type  of  function  or  the  other 
depending  upon  the  type  of  screen  you  are  using.  This  difference  is 
detailed  below. 

The  next  function,  color-testf ),  demonstrates  the  four  writing 
modes  in  conjunction  with  the  color  index  array  and  the  transparent 
copy  raster  function.  The  first  thing  done  is  clearing  the  screen  and 
drawing  a colored,  filled  rectangle.  The  checkerboard  raster  is  then 
placed  on  top  of  this  rectangle  using  the  various  writing  modes. 

Replace  mode  is  used  first  The  p^  coordinate  array  and  the  color 
index  array  are  set  If  a color  screen  is  used,  color  indices  2 and  3 are 
used  for  the  foreground  and  background,  respectively:  otherwise, 
black  (1)  and  white  (O)  are  used.  The  checkerboard  raster  is  copied 
onto  the  rectangle  using  the  replace  mode.  It  is  then  copied  using  the 
transparent  mode,  XOR  mode,  and  reverse  transparent  mode.  When 
color-testf ) has  finished,  the  program  terminates. 
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Results  from  Program  RASTER 

The  output  from  program  RASTER  should  be  studied  carefulfy.  This 
program  provides  }rou  with  a vast  amount  of  information  about  the 
way  the  Atari  ST  stores  and  displays  screen  Images. 

The  first  function  executed,  raBter_form( ).  produces  output  similar 
to  that  shown  in  Figures  7-7  and  7-8.  Tlie  figures  detail  the  process 
of  transforming  from  standard  format  to  device-specific  format  and 
from  device-specific  format  to  standard  format  Remember  that  stan- 
dard format  consists  of  contiguous  planes  with  all  of  one  plane 
followed  by  all  of  the  next  plane.  Device-specific  format  has  the  words 
of  each  plane  interleaved. 


Monodnonie  Output 

The  copy  raster  functions  produce  different  output  depending  on  the 
type  of  display  in  use.  The  results  presented  below  refer  to  output  on 
a monochrome  monitor. 

The  Ta8ter_test( ) function  draws  a pattern-filled  square.  Since  sav- 
ing a portion  of  the  screen  to  memory  produces  no  visible  restdts,  the 
first  thing  3TOU  see  is  a checkerboard  pattern  drawn  within  the 
pattern-filled  square.  After  3rou  press  a key,  a stripe  pattern  is  drawn 
that  overlaps  the  checkerboard  slightly.  Then  the  block  pattern  is 
shown.  After  the  next  key  press,  you  see  a rather  unusual  pattern  that 
is  the  result  of  the  copying  between  rectangles  of  different  sizes. 
Another  key  press  produces  another  strange  pattern.  If  you  get  two 
complete^'  filled  rectan^es  instead  of  these  strange  patterns,  your 
version  of  GEM  is  working  property.  On  the  author’s  computer,  these 
copy  operations  did  not  work  as  described  in  the  VDI  manual.  After 
another  key  press,  the  portion  of  the  screen  saved  in  the  temporary 
raster  is  restored  to  the  screen. 

At  this  point,  the  loop  repeats  and  the  copy  operations  use  the 
opaque  copy  raster  function  instead  of  the  transparent  copy  raster 
function.  For  a monochrome  display,  the  output  of  these  two  fimc- 
tlons  sqrpears  the  same. 

In  the  color-testO  function,  there  is  only  one  plane  in  the 
monochrome  mode,  and  therefore,  onty  one  bit  on  which  the  logic 
operations  can  be  performed.  First  the  black  rectangle  is  drawn.  Then 
the  checkerboard  raster  is  drawn  using  the  four  writing  modes.  The 
replace  mode  simply  places  the  checkerboard  pattern  on  the  screen. 
The  transparent  mode  makes  white  areas  appear  transparent  Thus, 
the  checkerboard  is  a black  euid  “clear”  image  on  a black  background 
and  nothing  shows  on  the  screen.  Ihe  XOR  mode  gives  the  reverse 
image  of  the  pattern.  The  reverse  transparent  mode  sets  all  0 bits  to 
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the  background  color  (white)  and  has  no  effect  on  the  1 bits;  the 
result  is  the  checkerboard  pattern  Itself. 

Color  Output 

The  results  of  the  color  display  are  somewhat  more  interesting.  The 
first  function,  the  raster _form( ) function,  produces  the  same  results 
as  before  (see  Figures  7-7  and  7-8).  In  the  raater-testf ) function,  the 
pattern-filled  background  square  is  drawn.  Then  the  checkerboard 
pattern  appears,  followed  the  striped  pattern  and  block  pattern. 
When  the  program  copies  rasters  with  rectangles  of  different  sizes, 
the  results  again  look  similar  to  the  monochrome  output  Finally,  the 
area  of  the  screen  saved  in  the  temporary  raster  is  restored.  So  far 
everything  looks  the  same  as  the  monochrome  ouqjut  The  transparent 
copy  raster  function  works  the  same  with  monochrome  or  color 
output 

If  you  have  a monochrome  monitor  and  a color  monitor  (or  televi- 
sion), you  may  notice  that  the  pattern  used  to  fill  the  background 
square  looks  different  on  a color  monitor.  This  is  probably  due  to  the 
lower  resolution  of  the  color  monitor  (or  television)  and  not  due  to  the 
copy  raster  functloiL 

At  this  point  the  program  is  ready  for  the  second  pass  through  the 
loop.  Now  the  program  uses  the  opaque  copy  raster  function.  After 
the  pattern-filled  square  is  drawn,  you  see  no  changes.  Press  a key, 
still  there  are  no  results.  In  fact  nothing  shows  on  the  screen  during 
this  pass  through  the  loop.  The  opaque  copy  function  does  not  work 
when  copying  from  a monochrome  raster  to  a color  raster.  In  this 
case,  the  program  is  tiylng  to  copy  a one-plane  monochrome  image 
onto  a four-plane  color  image.  Basically,  the  VDI  does  not  perform  an 
opaque  copy  between  rasters  that  have  a different  number  of  planes. 
This  makes  sense  because  an  opaque  copy  is  done  pixel  for  pixel;  if 
there  aren't  enough  pixels  to  suppfy  the  number  of  planes  being 
copied  to  or  from,  this  type  of  operation  doesn’t  make  sense.  The  VDI 
recognizes  this  situation  and  ignores  the  function  call. 

After  the  raater-test( ) function  is  completed,  the  program  moves 
on  to  the  color_teat( ) function.  On  the  color  monitor,  it  is  again  a 
little  more  interesting  than  on  the  monochrome  monitor.  The  func- 
tion draws  a colored  backgrotmd  rectangle  and  places  the  four  check- 
erboard patterns  on  the  rectangle.  The  actual  colors  shown  on  the 
screen  vary  depending  on  how  the  color  palette  Is  set  on  your  com- 
puter. Four  different  colors  are  shown  based  upon  the  four  different 
writing  modes  used.  As  an  exercise,  }rou  should  work  out  the  logic 
operations  of  the  four  writing  modes  between  the  color  of  the  back- 
ground rectangle  and  the  color  used  in  the  color-index  array.  You 
should  then  be  able  to  predict  which  colors  will  be  shown  for  each 
writing  mode. 
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Playing  uHth  Program  RASTEiR 

If  you  are  using  a color  monitor,  you  should  set  up  a raster  with  four 
planes  and  test  the  opaque  copy  function.  This  should  give  you  some 
results  on  the  second  pass  through  iaster-test( ).  Another  exercise 
would  be  to  chan^  the  function  to  store  the  portion  of  the  screen 
into  the  temporary  raster  area  from  opaque  to  a transparent  copy 
raster.  In  this  case,  the  screen  is  not  restor^  because  the  transparent 
copy  raster  function  is  designed  to  copy  from  a monochrome  raster 
to  a color  raster.  Unless  a monochrome  screen  is  used,  the  VDI  ignores 
the  function  call. 

Go  ahead  and  make  some  of  the  changes  suggested.  Try  other 
eiqieiiments  such  as  different  sized  rasters,  making  rasters  with  more 
planes,  and  so  on.  Remember  that  the  opaque  raster  function  must 
use  the  device-specific  format  If  it  is  easier  for  3rou  to  design  the 
raster  in  standard  format  go  ahead  and  do  that  and  then  use  the 
transformation  function  to  transform  the  raster  into  device-specific 
format 


Putting  It  All  Togethen  Program  BOUNCE 


Hie  program  BOUNCE  is  a culmination  of  aU  of  the  VDI  routines  and 
extended  BIOS  routines  you’ve  seen  so  far.  It  uses  rasters  and  the 
screen  bit  map  techniques  to  show  four  small  "balls”  bouncing  up 
and  down  and  across  the  screen. 

The  balls  start  In  the  upper  left  comer  of  the  screen.  Elach  is  given 
an  initial  horizontal  velocity  and  falls  under  a constant  acceleration 
(gravity).  When  a ball  hits  the  bottom  of  the  screen,  it  bounces  back 
up.  When  a ball  hits  the  side  of  the  screen  it  bovmces  off  the  side  and 
heads  in  the  opposite  direction. 

Putting  first  things  first  as  always,  we  take  a look  at  the  data  and 
data  structures  to  be  used  in  the  progiam.  There  is  the  usual  GEM 
application  overhead  including  the  MFDB  structure  declaration.  Un- 
der the  application-specific  data  there  are  three  defined  constants: 
W_BALL.  H JBALL,  and  NUM_BALLS.  W_BALL  and  H_BALL  define  the 
width  and  height  in  pixels  of  the  ball  raster  to  be  used.  NUM-BALLS 
determines  the  number  of  balls  to  eq>pear  on  the  screen. 

Because  each  ball  is  allowed  to  move  independently,  it  is  in  a 
unique  state  at  any  given  time.  In  particular,  each  ball  can  have  a 
different  position  on  the  screen  and  a different  vertical  and  horizontal 
velocity.  To  keep  track  of  this  information  in  an  organized  fashion, 
the  stmcture  BALL-REC  is  declared  in  the  sqipllcation-specific  data 
section.  In  this  structure,  there  are  two  x coordinates,  two  y coor- 
dinates, an  x velocity,  a y velocity,  and  a delay.  There  are  two  sets  of 
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coordinates  because  this  is  going  to  be  an  animated  program  like 
ANIMATE.  Therefore,  two  different  bit  maps  are  used  to  display  the 
moving  objects.  With  two  bit  maps,  there  must  be  two  sets  of  coor- 
dinates— one  for  each  bit  map.  The  integer  element  delay  is  used  to 
determine  when  each  ball  is  released.  This  allows  the  balls  to  start 
moving  independently. 

Two  pointers  to  the  screen  bit  maps,  bitmapO  and  bitmap  1,  are 
declared  next.  These  are  followed  by  two  integers,  draw-screen  and 
show-screen.  Variable  draw^scrccn  indicates  which  screen  (0  or  1) 
is  currently  being  drawn  on.  Variable  show-screen  indicates  which 
screen  is  currently  visible.  If  draw_screen  is  1.  then  show_screen 
must  be  0;  if  draw-Screen  is  0.  show-screen  must  be  1.  The  array  ball 
is  declared  to  have  as  many  elements  as  there  are  balls  (as  specified  by 
NUM_BALLS).  The  float  variable  gravity  determines  how  the  bcdls  are 
to  be  accelerated. 


Figure  7>9  Ball  Raster 
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There  are  four  memory  form  definition  blocks  (MFDBs)  declared: 
one  for  the  ball,  one  for  its  mask,  and  one  for  each  screen.  Figure 
7-9  shows  the  raster  for  the  ball.  The  grid  In  the  figure  Is  48  boxes 
by  48  boxes,  corresponding  to  a 48-by-48  pixel  raster.  Just  as  with 
the  pattern  rasters  in  program  RASTER,  the  image  is  divided  into 
4-pixel  horizontal  groups,  which  are  translated  Into  hexadecimal 
notation  (see  Figure  7-9).  Another  advantage  of  using  rasters  is  that 
the  raster  image  can  be  changed  quite  easily.  You  may  want  to  change 
the  ball  to  have  a different  pattern  on  its  face  or  look  like  something 
completely  different  such  as  a pogo  stick. 

Once  the  hexadecimal  codes  for  the  ball  raster  have  been  deter- 
mined, they  must  be  stored  in  memory  so  that  the  VDI  can  use  them 
as  a raster.  The  raster  Is  held  in  array  ball-shape.  Note  that  the 
arrays  dimensions  are  48  by  3.  Looking  at  Figure  7-9,  you  can  see 
two  heavy  vertical  lines  that  divide  the  raster  into  three  16-bit  groups 
and  that  there  are  48  lines  (rows)  vertically.  These  physical  dimen- 
sions determine  the  dimensions  of  the  array.  The  raster  is  three  words 
wide  (16  bits  per  word)  and  48  rows  high. 

Consider  the  following  animation  technique.  The  ball  is  drawn  at  a 
certain  point  on  the  screen  with  aU  dark  areas  of  the  ball  denoted  by 
bits  with  a value  of  1 and  all  white  areas  denoted  by  bits  with  a value 
of  0.  To  make  the  ball  appear  to  move.  It  is  first  redrawn  In  the  same 
location  using  the  XOR  writing  mode,  which  in  effect  erases  the 
image.  The  ball  is  then  drawn  in  its  new  position  using  the  normal 
replace  mode  (or  XOR  mode  again).  The  new  image  is  erased  and  the 
next  image  is  drawn  in  a new  location.  By  repeating  this  quickly 
enough,  the  ball  appears  to  move. 

This  program,  however,  uses  not  one  but  four  balls  on  the  screen 
at  one  time.  Since  the  balls  will  cross  paths,  the  program  must  be 
able  to  draw  the  balls  so  that  they  appear  to  be  on  top  of  each  other. 
Whenever  one  ball  is  drawn  on  top  of  the  other,  it  should  appear  as 
if  that  ball  is  In  front  of  the  other.  In  other  words,  the  top  ball  should 
partially  or  totally  mask  the  other  ball  or  balls  it  covers.  You  can’t  use 
replace  mode  because  the  raster  is  square;  the  portion  of  the  raster 
around  the  ball  would  also  be  drawn  on  the  screen  and  you  would  get 
a shadow  around  the  ball.  You  can’t  use  transparent  mode  because 
anything  beneath  the  ball  would  show  through  the  white  stripe. 
Reverse  transparent  mode  would  draw  the  ball  Incorrectly.  If  the  XOR 
writing  mode  were  used,  a “checkerboard”  pattern  would  appear 
where  the  balls  overlap.  This  means  that  any  place  a black  portion  is 
drawn  over  a black  portion  appears  white  and  any  place  a white 
portion  is  drawn  over  white  appears  black.  Therefore,  this  would  not 
give  the  proper  Image. 

A method  is  needed  that  erases  the  portion  of  the  screen  under  the 
topmost  ball  so  nothing  shows  through  the  topmost  ball.  This  is 


168  Atari  ST 


accomplished  through  the  use  of  a mask.  A mask  is  a raster  that  has 
all  its  bits  set  to  1 wherever  the  image  should  appear  solid.  If  you  use 
a mask,  you  can  draw  over  an)rthing  using  transparent  mode  so  that 
the  square  edges  do  not  show  and  erase  the  area  around  the  image. 
Then  draw  the  actual  image.  The  mask  for  the  ball  in  this  program 
covers  any  area  of  the  raster  covered  by  the  ball.  Thus,  the  mask  is  just 
a filled  circle  (essential^  the  ball  Itself  without  the  white  stripe  in  the 
middle).  The  mask  raster  Is  initialized  in  the  array  ball -mask.  With 
the  help  of  graph  p^r.  you  can  verify  that  the  values  in  ball-mask 
correspond  to  such  a fllled-in  circle.  The  area  in  the  mask  not  covered 
by  the  ball  has  Its  bits  set  to  0. 

Other  examples  of  a mask  are  readily  apparent  On  the  desktop,  for 
example,  the  disk  icons  and  the  trash  can  icons  are  held  in  memoiy 
as  rasters  and  have  corresponding  masks.  The  masks  look  like 
shadows  of  the  Icons.  The  mouse  cursor  also  has  a mask,  adiich  is 
most  noticeable  when  it  looks  like  a finger.  The  finger  is  filled  with 
white  so  a mask  is  used  to  make  the  inside  of  the  hand  £q>pear  solid. 


Operatioii  of  Program  BOUNCE 


Program  BOUNCE  contains  most  of  the  gr£q>hic  techniques  shown  in 
the  preceding  chapters.  Rasters,  multiple  screens,  and  masks  are  used 
to  show  the  bouncing  balls.  At  the  top  of  the  program,  the  usual  GEM 
routines  initialize  access  to  the  workstation.  In  the  application- 
specific  routines,  the  set-bitmap( ) fimctlon  is  a modified  version  of 
the  set-base( ) function  used  in  ANIMATED  This  routine  returns  the 
address  of  the  current  screen  bit  map  and  sets  the  parameter  to  the 
address  of  a new  screen  bit  map.  This  allows  any  future  programs  to 
use  any  variable  name  you  want  for  the  bit  map  addresses.  The 
function  set-iqi-fastersf ) sets  up  the  rasters  for  the  ball,  the  mask, 
and  both  screens. 

In  the  general  control  flow  of  the  program  in  mainO.  the  ap- 
plication-specific functions  start  by  initializing  the  bit  map  addresses 
and  the  raster  MFDBs  (see  Listing  7-2).  The  program  then  enters  a 
loop  that  controls  the  execution  of  the  program  from  this  point  on. 
First,  the  display  screen  and  drawing  screen  are  set  and  cleared.  ITien 
the  ball  array  is  initialized  in  init-ba]l( ) and  function  boimce-ball( ) 
is  called  to  start  the  animation  sequence.  Function  boniice-ball( ) 
returns  when  a key  has  been  pressed.  Upon  Its  return,  the  loop  In 
main( ) checks  If  the  key  pressed  is  the  ESC  key.  If  the  ESC  key  is 
pressed,  the  program  is  exited;  otherwise,  the  program  starts  the  balls 
bouncing  again.  On  exiting,  the  program  meikes  sure  the  screen  is  set 
to  the  original  bit  map,  the  secondary  bit  msq)  memoiy  is  released, 
and  the  virtual  workstation  is  closed. 


Moving  Targets  169 


Listing  7-2  Program  BOUNCE 

BOUNCE. C Drau  bouncing  balls 

This  program  demonstrates  an  animation  technique  using 
raster  operations. 

System  Header  Files  t Constants 


ninclude 

<8tdlo.h> 

Standard  10 

tllnclude 

<osblnd.h> 

/» 

GEMDOS  routines 

tllnclude 

<gsmdefs.h> 

/» 

GEM  RES  »/ 

ninclude 

<obdefs.h> 

GEM  constants 

ttdeflne  FRLSC  0 

ttdeflne  TRUE  IFflLSE 

/«»«##«««« «««««#«««« #««««««#«#««#««##«««»# »«««#«««« 

GEM  Rppllcatlon  Overhead 

Declare  global  arrays  for  VDI. 

typedsf 

Int  UORD; 

/* 

UORD  Is  16  bits 

UORD 

contrl(12]. 

VDI  control  array 

lntout[128],  lntln[12B] 

, 

VDI  Input  arrays 

ptsln[12B],  ptsout[12B] 

VDI  output  arrays 

UORD 

8creen.uhandle, 

virtual  screen  workstation 

screerL43hand  1 e , 

✓» 

physical  screen  workstation 

screen^ez. 

y* 

screen  resolution  0,1,  or  2 

color-screen. 

y* 

flag  if  color  monitor 

x-max. 

y* 

max  X screen  coord 

y-(nax; 

y* 

max  y screen  coord 

typodef 

{ 

char 

struct  mfdbstr 

y* 

GEM  data  structure 

»addr; 

y* 

address  of  raster  area 

UORD 

ulde; 

y* 

width  of  raster  In  pixels 

UORD 

high; 

y* 

height  of  raster  In  pixels 

UORD 

uord-uldth; 

✓» 

width  of  raster  in  words 

UORD 

format; 

/» 

standard  or  device  specific 

UORD 

planes; 

y* 

number  of  planes  In  raster 

UORD 

reserul,  r8Sor\;2,  reseruB; 

} MFDB: 


/«#««««««««#«##«##«#«#«««*##)(«««««««««««««««««««»«« 
Rppllcatlon  Specific  Data 
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Listing  7*2  (continued) 

Udefine  U.BRLL  AS 

ttdefine  HJBRLL  48 

tide  fine  NUM_BRLLS  4 

typedef  struct 

Int  x(2); 

int  y(2); 

float  dx; 
float  dy; 

Int  delay; 

> BfiLL_REC; 

char  *bltmap0, 

*bl tmapl; 

Int  drau_5creen, 
ehow^creen; 

8RLL-REC  ba 1 1 [ NUh_BRLL5 ] ; 

float  gravity; 

WFDB  ballMFDB, 
maskhFOB, 

8crMFDB(2]; 


uldth  of  ball  raster 
height  of  ball  raster 
number  of  balls  to  drau 


/»  X coord  for  each  screen 
y coord  for  each  screen 
X velocity 
y velocity 
release  delay  timer 


/»  screen  bitmaps 


0 or  1;  determines  which 
/*  screen  to  use  for  draulng 

a record  for  each  ball  */’ 

acceleration 

raster  descriptors 

one  for  each  screen 


define  shapes 

Int  ball^hape[48]  [3]  = { Line 

0x0000 « 0x0000,  0x0000,  0 

0x0000,  0x0ff0,  0x0000, 

0x0000,  0xffff,  0x0000, 

0x0003,  0xffff,  0XC000, 

0x0007,  0xffff,  0X6000, 

0x001f,  0xffff,  0xf800, 

0x007f,  0xffff,  0xfe00, 

0x00ff,  0xffff,  0xff00, 

0x01ff,  0xffff,  0xff80,  B 

0x03ff,  0xffff,  0xffc0, 

0x07ff,  0xffff,  0xffe0, 

0x07ff,  0xffff,  0xffe0, 

0x0fff,  0xffff,  0xfff0, 

0x0fff,  0xffff,  0xfff0, 

0xlfff,  0xffff,  0xfff8, 

0xlfff,  0xffff,  0xfffB, 

0x3fff,  0xffff,  0xfffc,  IS 

0x3fff,  0xffff,  0xfffc, 

0x3fff,  0xffff,  0xfffc, 

0x3fff,  0xffff,  0xfffc, 

0x4fff,  0xffff,  0xfff2, 

0x43ff,  0xffff,  0xffc2, 
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Listiiig7-2  (continued) 

0x40ff,  0xffff,  0xff02, 

0x401f,  0xffff,  0xfB02, 

0x4001,  0xffff,  0x8002,  24 

0x4000,  0x07e0,  0x0002, 

0x4000,  0x0000,  0x0002, 

0x4000,  0x0000,  0x0002, 

0x2000,  0x0000,  0x0004, 

0x3800,  0x0000,  0x001c, 

0x3a00,  0x0000,  0x007c, 

0x3fB0,  0x0000,  0x01fc, 

0xlff0,  0x0000,  0x0ffB,  32 

0xlfff,  0x0000,  0xfffB, 

0x0fff,  0xffff,  0xfff0, 

0x0fff,  0xffff,  0xfff0, 

0x07ff,  0xffff,  0xffe0, 

0X07ff,  0Xffff,  0xffB0, 

0x03ff,  0xffff,  0xffc0, 

0x01ff,  0xffff,  0xffB0, 

0x00ff,  0xffff,  0xff00,  y*  40 

0x007f,  0xffff,  0xfB00, 

0x001f,  0xffff,  0xfB00, 

0x0007,  0xffff,  0XB000, 

0x0003,  0xffff,  0XC000, 

0x0000,  0xffff,  0X0000, 

0X0000,  0X0ff0,  0X0000, 

0x0000,  0x0000,  0X0000 

>; 

Int  bail^a8k[48]  [3]  = ( Lins 

0X0000,  0X0000,  0X0000,  0 

0X0000,  0X0ff0,  0X0000, 

0X0000,  0Xffff,  0X0000, 

0x0003,  0xffFf,  0XC000, 

0X0007,  0xffff,  0XB000, 

0X001F,  0xffff,  0xfB00, 

0X007F,  0xffff,  0xfa00, 

0x00ff,  0xffff,  0xff00, 

0x01ff,  0xffff,  0xffB0,  0 

0x03ff,  0xffff,  0xffc0, 

0x07ff,  0xffff,  0xffe0, 

0x07ff,  0xffff,  0xffB0, 

0x0fff,  0xffff,  0xfff0, 

0X0fff,  0xffff,  0xfff0, 

0xlfff,  0xffff,  0xfff0, 

0xlfff,  0xffff,  0xfff0, 

0x3fff,  0xffff,  0xfffc,  16 

0x3fff,  0xffff,  0xfffc, 

0x3fff,  0xffff,  0xfffc, 

0x3fff,  0xffff,  0xfffc, 

0x7fff,  0xffff,  0xfffB, 

0x7fff,  0xffff,  0XfffB, 

0x7fff,  0xffff,  0xfffB, 
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Listliig  7-2  (continiied) 

0x7fff,  0xffff,  0xfff0, 

0x7fff,  0xffff,  0xfffe,  y*  24 

0x7fff,  0xffff,  0xfffe, 

0x7fff,  0xffff,  0xfffe, 

0x7fff,  0xffff,  0xfffe, 

0x3fff,  0xffff,  0xfffe, 

0x3fff,  0xffff,  0xfffc, 

0x3fff,  0xffff,  0xffFc, 

0x3fff,  0xffff,  0xfffc, 

0xlfff,  0xffff,  0xfff0,  32  *y 

0xlfff,  0xffff,  0xfff0, 

0x0fff,  0xffff,  0xfff0, 

0X0fff,  0Xffff,  0xfff0, 

0x07ff,  0xffff,  0xffo0, 

0x07ff*  0xffff,  0xffe0, 

0x03ff,  0xffff,  0xffc0, 

0x01ff,  0xffff,  0xff80, 

0x00ff,  0xffff,  0xff00,  /«  40 

0x007f,  0xffff,  0xfB00, 

0x001f,  0xffff,  0xf800, 

0X0007,  0Xffff,  0XG000, 

0x0003,  0xffff,  0XC000, 

0X0000,  0xffff,  0X0000, 

0X0000,  0X0ff0,  0X0000, 

0X0000,  0X0000,  0X0000 

>; 

GEM-related  Functions 

UORD  open_v/uork(phys^andle) 
t40RD  phys-handle; 

Function:  This  function  opens  a virtual  uorkstatlon. 

Input:  phys^andie  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

WORD  uork^n[ll], 

uorl<-jout[57], 

new-handlo;  handle  of  workstation  *y 

Int  1; 

for  (1=0;  i < 10;  1++)  set  for  default  values 

work-.ln(lJ  = 1; 

uork_ln(10]  = 2;  /'»  use  raster  coords 

new_handle  = phys-handle;  use  currently  open  wkstatlon 

v.^pnvuk(uorlx^n,  &neuJiandle,  uorl<^ut); 
return  (neu.J>andle) ; 

> 
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Listing  7-2  (continued) 

88t-J8creBn_jattr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  8creen.vhandle. 

Output:  Sets  >cjnax,  y.jnax,  color^creen,  and  screen^ez. 

{ 

UQRD  uark^ut[S7); 

vq^xtnd(screenu.vhandle,  0,  uork^ut); 
x-max  = uorl<uout[0] ; 
y_max  » uork^ut[l]; 

screen.rez  « 6etrez();  /»  0 = low,  1 = roed,  2 = high 

color.jscreen  = (screen_rez  < 2);  mono  2,  color  0 or  1 

> 

Application  Functions 

long  Rnd^ng(lou,  hi) 
long  low,  hi; 

Function:  Generate  a random  number  between  low  and  hi.  Inclusive. 
Input:  low  = lowest  value  In  range. 

hi  = highest  value  In  range. 

Output:  Returns  random  number. 

( 

hl++;  Include  hi  value  in  range  */ 

return(  (Random()  % (hi  - low))  * low); 

> 

char  *set_bl  tmap(nebLjnap) 
char  **newL_map; 

/««««««««»»«««««««««««««««»»»«««»««««««««««««««««»« 

Function:  Allocate  memory  for  new  screen  bitmap. 

Input:  new^ap  = pointer  to  a pointer  for  the  new  bitmap. 

Output:  Returns  current  bitmap  address  and  sets  neu_map 

to  address  of  new  bitmap  location. 

< 

long  x; 

allocate  new  screen  bitmap 

X = (long)Malloc(32256L);  /«  get  32  kbytes 
if  (!(x  as  256))  on  half  page  boundary  »/ 

^neuLjnap  = (char  *)  x; 

else  move  to  boundary 

*neu_map  = (char  *)(x  + (256  - (x  at  256))); 
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Listiiig7-2  (continned) 

/*  return  current  bitmap 

return(  (char  *)Logbase()  ); 

> 

set^p^asters( ) 

Tunctlon:  Sets  up  global  MFDB  to  point  to  rasters. 

Input:  None.  Uses  global  FOBs  and  rasters  listed  above. 

Output:  Sets  appropriate  fields  In  FDBs. 

{ 


Ball  raster  */ 
ballMFOB.addr 
ballNFDB.uide  = 

ballMFDB.high 
ballMFDB.uordLuidth  = 
ballMFDB. format  = 

ballMFDB. planes  = 


(char  *)ball^hape; 

W-BRLL;  uldth  In  pixels 

H.BRLL;  height  in  pixels 

3;  uildth  in  UORDs 

0; 

1;  monochrome  has  1 plane 


Mask  raster 

maskMFDB.addr  = (char  *)ball-mask; 

maskMFDB.ulde  = ULBRLL;  uildth  In  pixels 

maskMFDB.hlgh  = H.BRLL;  height  in  pixels 


maskMFDB.uordjuildth  = 3; 

maskMFDB. format  = 0; 

roaskMFDB . p 1 anes  = 1 ; 

/*  Screen  raster  area 

scrMFD8[0].ulde  = 

scrMFDB[0] .high  = 

scrMFDB(0] .uord_uLdth  = 

scrMFDB(0] . format  = 

scrMFDB[0] .planes  = 

if  (screen_rez  ==  0) 

{ 

scrMFDB[0]  .uilde  = 

scrMFDB(0] .high  = 

scrMFDB[0]  .uorcLjjidth  = 
scrMFDB[0] .planes  = 

else  If  (screeriL-rez  ==  1) 

{ 

scrMFDB[0] -ulde  = 

scrMFDB[0] .high  = 

scrMFDB[0] .planes  = 

> 


uildth  In  WORDS  */ 
monochrome  has  1 plane 


640; 

400; 

40; 

0; 

1;  monochrome  has  1 plana 

lou  resolution 

320; 

200; 

20; 

4; 

medium  resolution 

640; 

200; 

2; 


second  bitmap  same  as  first 

scrMFDB(l] .ulde  = scrMFDB[0] .ulde; 

scrMFDB(l] .high  = scrMFOB[0] .high; 
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Ustliig7-2  (contiiitied) 

8crnrDB[l] .uorcL-Mldth  = scrMFDB(0) .word-width; 

8crMFDB[l] .format  = scrMFDB[0] .format; 

scrMFDB[l) .planes  = scrMFDB[0J .planes; 

scrMFOB [ 0 ] • addr  = b 1 tmap0 ; 

scrMFDB[l] .addr  « bltmapl; 

return; 

> 

init-ball() 

Function:  Initialize  bail  uariables. 

Input:  None. 

Output:  Set  ball  position,  mov/ement,  and  speed. 

»««««««««««««««««««««««««««««««««««»»»«»««»«»««»««/ 

{ 

int  1; 

UORD  uorl<-jout(S7] ; 

get  distance  between  pixels 
uq-extnd(8creerL.vhandls,  0,  uork-out); 

determine  acceleration  factor 
gravity  = 9B00000  ^ ( 3600  « (f loat)uorkuout[4] ) ; 

for  (I  = 0;  I < NUM-BRLLS;  i++) 

< 

ball(l].x(0]  = ball(i]-x(l]  = 0; 

bail[i].y[0]  » bali[i].y[l]  0; 

ball[i].dx  = RndL-rng(lL,  10L);  x movement 

ball[i).dy  = 0;  start  at  top  of  arc 

ball[i] .delay  ° RndLrng(lL,  100L); 

) 

draw-hall (x,  y) 

UDRD  X,  y; 

Function:  Draw  a bail  at  the  specified  coordinates. 

Input:  X s X coord  of  upper  left  corner. 

y = y coord  of  upper  left  corner. 

Raster  must  be  set. 

□utput:  None. 

{ 

UORO  pxy(8], 

color.index[2] ; 

color-.index[0]  = 1;  Foreground  color  value 

color^ndex[l]  = 0;  Background  color  value  *y 
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Ustliig7-2  (continiied) 


Sot  coordinate  array 
pxy(0]  = 0; 
pxy(l]  = 0; 
pxyI2]  = W»BflLL  - 1; 
pxy(3]  a - 1; 

pxy[4)  = x; 
pxytS]  = y; 
pxy[SJ  = x + pxy[2]; 
pxy[7]  = y + pxy[3); 


soLirco  xl  coord 
source  yl  coord  »/ 
source  x2  coord 
/*  source  y2  coord 
dest  xl  coord 
dest  yl  coord 
dest  x2  coord 
dost  y2  coord 


use  mask  to  erase  area  under  ball 

color_lndex[0]  ° 0;  1 bits  set  to  background  color 

urt^pyfm(screBn_vhandle,  K0.TRRN5,  pxy, 

&maskMFDB,  &ecrl1FD8(drauLJscreBn] , color^ndex); 


draw  ball 

color^ndex[0]  » 1;  1 bits  sot  to  foreground  color 

urt^pyfffl(scresrL.uhandle,  M0.TRRN5,  pxy, 

&ballMFDB,  &scrMFDB[drauuscre0n] , color^ndex); 

) 


erase^all(x,  y) 

WORD  X,  y; 

Function:  Draw  a ball  at  the  specified  coordinates. 
Input:  X ax  coord  of  upper  left  corner. 

y ay  coord  of  upper  left  corner. 
Rasters  must  be  set. 

Output:  None. 

I4QRD  pxy[8], 

coior^ndex[2]; 


color.lndex[0]  » 0; 
color.lndex[l]  = 0; 

Sot  coordinate  array 
pxyI0)  = 0; 

pxy(l]  = 0; 

pxy(2]  = U_BRLL  • 1; 

pxy[3]  ° H_BnLL  - 1; 

pxy(4]  = x; 

pxy(S]  = y; 

pxy(G]  = X + pxy(2]: 
pxy(7]  = y + pxy[3]; 


Foreground  color  ualue 
Background  color  ualue 


source  xl  coord 
✓»  source  yl  coord 
source  x2  coord 
✓»  source  y2  coord  */ 
dest  xl  coord 
dost  yl  coord 
dest  x2  coord 
✓»  dest  y2  coord 


y*  use  mask  to  erase  area  under  ball 

color_lndex(0]  =0;  1 bits  set  to  background  color 

urtucpyfm(8crBen.uhandle,  MD.TRRNS,  pxy, 

&maskMFDB,  &scrMFDB[drau^creen] , color^ndex); 


> 
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calc,bali( ) 

Function:  Calculate  neu  position  for  balls. 

Input:  Uses  ball  position  variables. 

Output:  Neu  ball  position*  acceleration*  and  direction. 

{ 

int  i; 


for  (i  = 0;  1 < NUM-BftLLS;  i++) 

< 

ball[i]. delay--; 
if  (ball[i] .delay  > 0) 
continue; 


ball[i].dy  +=  gravity; 
change  position 

ball[i] .y[drau.j5creen]  » ball[ i].y[show-screen]  ^ bali[i].dy; 
ball [ i] .x[drau— screen]  s ball[i).x[shouLJ3crBen]  ball[i].dx; 


count  down  */ 
do  not  release  ball 


chango  velocity 


chock  range 

loft  edge 

if  (ball[i].x[draw-screen]  < 0) 

< 

ball[i]  .x[drau.j5creen]  =0; 
ball[i].dx  = -ball[i].dx; 

> 

right  edge  less  width  of  ball 
if  (ball[i] .x[drau.jBcreen]  > (x-max  - U_£RLL]] 
< 

ball[i] .x[draw.jBcreen]  = x_max  - l*LfiRLL; 
ball[i].dx  s -ball[i].dx; 

> 


/»  top  of  screen 

if  (ball[i] .y[drau_Bcreen]  < 0) 

{ 

ball[i]  .y[draw.j5creen]  = 0; 
ball[i].dy  » 0; 

> 

bottom  of  screen 

if  (ball[i] .y[drau_screen]  > (y.jnax  - H_BRLL)) 

{ /«  at  bottom  of  arc  ball  bounces  losing  energy 

ball[i] .y[drauu.screen]  = y_max  - H..SRLL; 
ball[i].dy  = -ball[i].dy  * 0.375; 

> 

> 

return; 

> 
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bounce^all( ) 

Function:  Bounce  balls  on  screen. 

Input:  None. 

Output:  None. 

{ 

Int  1; 
do 

{ /»  draw  balls  on  hidden  screen 

for  (1  = 0;  1 < NUM-BftLLS;  1++) 

drau_ball(ball[i].x[drau^creen] , ball[l] .y[drauLJScreen] ) ; 
sul tch  screens 

If  (drauLJBcreen) 

{ 

drauLJBcrsen  = 0; 
shou_screen  = 1; 

> 

else 

{ 

draw_jBcreen  ~ 1; 
shouL-scresn  = 0; 

> 

Se tscreen ( 8crNFDB[ drawuscreen ] . addr , 

8crKFDB[shouuGcreen] .addr«  *1L) ; 

VsyncO; 

✓a  erase  balls 

for  (1  s 0;  1 < NUM-BftLLS;  1++) 

e rasB-ba ll(ball[l].x[d rau^c reen ] , ba  1 1 ( 1 ] . y [ drawee reen ] ) ; 

calc  new  ball  positions 

calc_ball() ; 

} while  (!Cconls()); 

> 

Main  Program 

maln( ) 

{ 

Int  ap^d;  application  inlt  verify 

NORD  grjwchar,  gr^char,  values  for  VOI  handle 

gr^box«  gr^box; 

Initialize  GEM  Recess 
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Ustliig7>2  (continued) 

ap_id  = appl—inltO;  Initialize  RES  routines 

if  (ap_id  < 0)  no  calls  can  be  made  to  flES 

{ use  GEMDOS 

Cconws(“***>  Initialization  Error.  <*»*Nn“); 

Cconws( "Press  any  key  to  continue. ^n" ) ; 

Craucin( ); 

exit(>l);  set  exit  value  to  show  error 

> 

screen_phandie  = Got  handle  for  screen 

graf Jiandie(&gr^char,  &grJ^char«  &gr^box,  &gr_hbax); 
screeruvhandle  = open— vuorl<(screenL-phandle) ; 
set^creerLjattr( ) ; Get  screen  attributes 


Rppiication  Specific  Routines 


bitmap0  - sst-bitmap(&bitmapl); 
set .up  rasters 0 ; 
do 

< 

show— screen  =0;  /* 

drat«ujscreen  = 1; 
5etscreen(bitmapl,  -IL,  -IL); 
v^lruk(scre0n_vhandle) ; 
5etscreen(bi tmap0,  -IL,  -IL); 
V.JC1  ruk  ( screen— vhandle ) ; 
init-ball(); 
bounce_baii( ) ; 

) while  ( (CrawcinO  & 0x7F)  !=  27); 


set  to  current  screen 
set  to  background  screen 
clear  screens 


exits  on  keypress 


*/ 


Program  Clean-up  and  Exit 


Setscreen(bitmap0«  bitmapO, 
Mfree(bitmapl) ; 
v_c  i s vwk  ( sc  r een-jvhand  i e ) ; 
appl— exit( ); 


•IL); 

return  secondary  bitmap 
close  workstation  »/ 
end  prorgram 


As  for  the  application-specific  functions  of  the  program,  the 
Rnd-ingf ) range  function  and  the  set-bitnuy>( ) function  have  each 
been  seen  before.  The  8ct-iq>-iastex8( ) function  sets  the  MFDBs  of  a 
monochrome  raster  in  device-specific  format  for  the  ball  and  mask. 
These  are  both  three  words  wide.  An  MFDB  for  each  display  screen 
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is  also  set  up.  The  only  difference  between  the  dlspk^  screens  Is  their 
euldress. 

Function  Inlt  ball( ) performs  an  initialization  of  the  ball  recorda 
The  first  thing  the  function  does  is  to  make  an  extended  Inquliy 
requesting  the  open  workstation  values.  Element  4 of  the  array 
work-out  is  a value  that  indicates  the  distance  between  the  top  of  one 
pixel  and  the  top  of  the  next  pixel.  This  distance  is  measured  in 
microns  (1  micrometer  = 1/1.000.000  meter)  and  is  used  to  determine 
the  value  for  gravity.  Gravity  is  computed  in  terms  of  pixels  per  frame. 
A frame  is  considered  to  be  1/60  of  a second— the  refresh  cycle  time. 
After  gravity  hets  been  calculated,  each  ball  record  is  then  set  to  its 
initial  values.  All  balls  start  in  the  upper  left  comer.  An  x velocity  is 
selected  randomfy,  and  the  y velocity  is  set  at  0.  The  delay  is  also 
randomly  chosen  so  that  the  balls  are  released  at  different  times. 

Function  dzaw-ball( ) draws  a ball  at  the  given  x and  y coordinates. 
These  coordinates  specify  the  upper  left  comer  of  the  source  raster 
on  the  destination  raster.  As  usual,  the  arrays  color-index  and 
are  required.  The  color  1 is  used  as  a foreground  color  and  the  back- 
ground color  is  set  to  0.  The  array  has  its  first  fovir  coordinates 
set  to  the  size  of  the  source  raster,  which  has  opposite  comers  at  (0,0) 
and  (47,47).  The  destination  coordinates  are  then  set  The  upper 
left  coordinates  are  set  at  (x,y)  and  the  lower  right  coordinates  are 
determined  and  set  by  adding  on  the  size  of  the  source  raster. 

Since  the  area  tmder  the  ball  must  be  erased,  the  mask  is  drawn 
first  The  foreground  color  is  set  to  the  background  color  and  the 
transparent  copy  raster  function  is  used.  Remember  that  the  trans- 
parent copy  raster  function  works  with  both  color  and  monochrome 
screens.  The  function  draws  with  the  transparent  mode  to  copy  the 
mask  to  the  screen.  The  transparent  mode  is  used  because  any  place 
there  is  a 0 in  the  mask  raster,  the  screen  is  not  changed.  Any  place 
there  is  a 1 in  the  mask  raster,  the  background  color  is  drawn. 

Once  the  mask  has  been  drawn,  the  color  is  set  back  to  the 
foreground  color  and  the  ball  raster  is  drawn  on  the  area  just  erased. 
Again  the  transparent  mode  is  used:  where  there  is  a 0 in  the  raster, 
no  action  mkes  place. 

The  next  fimctlon,  erase-ballf ),  erases  the  ball  from  the  screen  at 
coordinate  (x,y).  This  function  is  the  same  as  the  dzaw-ball( ) func- 
tion except  that  the  ezase-ballf)  function  stops  after  erasing  the 
screen. 

Calc-ball( ) calculates  the  new  position  of  each  ball  in  a loop.  This 
function  is  called  for  each  new  frame  (refresh  cyde).  The  delay  value 
for  each  ball  is  decremented  and  tested.  If  the  value  is  still  positive, 
the  delay  has  not  been  completed  and  the  loop  continues.  If  the  ball 
is  ready  to  be  released  or  has  already  been  released,  the  y velocity  is 
increased.  The  new  position  is  calculated  based  upon  the  velocity  and 
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the  X and  y values  of  the  ball’s  current  position  (the  position  on  the 
screen  now  being  shown).  The  new  x and  y positions  are  held  in  the 
X and  y values  for  the  screen  used  for  drawing.  If  the  ball  is  to  be 
drawn  at  the  next  position,  the  calculation  must  obviously  take  into 
accoimt  the  present  position  and  the  present  velocity. 

Once  the  new  position  of  the  ball  is  determined,  the  Anal  step  is  to 
check  if  the  ball  has  gone  bQrond  the  edges  of  the  screen.  If  the  ball 
has  gone  past  the  left  edge,  the  x position  is  set  to  0 and  the  x velocity 
of  the  ball  is  reversed.  If  the  ball  goes  past  the  right  edge  (adjusted 
for  the  width  of  the  ball),  the  position  is  set  to  the  right  edge  (minus 
the  ball’s  width)  and  the  x velocity  is  reversed.  If  the  ball  goes  above 
the  top  of  the  screen  (which  should  not  occur  but  should  be  tested 
for  safety),  the  y position  is  set  to  the  top  of  the  screen  and  the  y 
velocity  becomes  0 (the  top  of  the  arc).  When  the  ball  hits  the  bottom 
of  the  screen,  it  should  bounce.  The  y value  Is  set  to  the  bottom  of 
the  screen  (adjusted  for  the  height  of  the  ball)  and  the  ball’s  y velocity 
is  reversed  and  decreased  sUghtly.  In  nature,  a rubber  ball  does  not 
continue  to  bounce  forever.  When  a ball  strikes  the  ground,  it  bounces 
up  at  a slightly  slower  velocity  than  when  it  hit  In  this  program,  the 
upward  speed  is  set  to  97.5%  of  the  downward  speed. 

Function  boance-ball( ) is  simply  a loop.  First  it  draws  all  balls  on 
the  drawing  screen.  Next  the  screens  are  swapped  and  a pause  for 
vertical  synchronization  is  made.  Then  the  balls  are  erased  from  the 
new  drawing  screen  (the  one  that  has  just  been  swapped  from  being 
visible)  and  the  new  ball  positions  are  calculated.  When  the  user 
presses  a key,  the  loop  ends  and  bonnce_ball( ) returns  to  Amctlon 

Note  that  the  screen  is  alwajrs  drawn  in  its  entirety.  In  other  words, 
the  four  balls  are  erased  from  the  screen  by  eiase_ball( ),  which 
makes  the  screen  blank.  Then  four  new  balls  are  drawn  on  the  screen. 
This  is  the  basic  Aow  for  almost  any  type  of  animation  program  even 
if  you  want  to  have  a complex  background  on  the  screen.  The  primary 
objective  when  writing  an  animation  program  is  to  do  all  drawing  as 
fast  as  possible  to  reduce  the  amount  of  flicker.  When  you  have  a 
background — even  a simple  one,  it  is  time-consuming  to  erase  the 
screen,  redraw  the  background,  and  then  draw  the  shapes  (in 
BOUNCE  the  shapes  are  the  balls).  To  solve  this  problem,  you  start 
with  the  background.  Now  assume  you  are  drawing  balls  on  the 
background.  E^ch  time  you  draw  new  balls,  you  first  save  the  area 
under  each  ball  to  be  drawn  in  a temporary  raster,  similar  to  the 
procedure  used  in  program  RASTER  Draw  the  balls  using  the  mask 
and  shape  raster. 

To  erase  the  shapes,  instead  of  erasing  the  balls  from  the  screen, 
simply  replace  the  saved  portion  of  the  screen.  This  writes  over  the 
shape  and  restores  the  background  at  the  seune  time.  You  must  save 


182  Atari  ST 


the  rasters  before  anything  is  drawn  on  the  screen;  otherwise,  only 
part  of  a ball  may  be  saved.  In  other  words,  the  rasters  are  saved  first 
the  balls  are  drawn,  and  then  the  rasters  are  replaced.  If  you  want  to 
try  this,  fill  in  the  background  of  the  screen  and  make  the  necessary 
changes  to  the  program.  Enter  program  BOUNCE  into  your  ^tem, 
and  check  it  out 


Say  “Good-bye"  to  the  VDI 


At  this  point  most  of  the  VDI  functions  have  been  covered.  In  this 
chapter,  you  learned  about  one  of  the  more  complex  and  powerful 
concepts  of  the  VDI— the  raster.  With  the  raster,  3tou  are  able  to 
efficiently  write  animated  programs  and  provide  fast  graphic 
responses  within  your  programs  through  the  use  of  icons  and  pic- 
tures. 

The  next  chapter  deals  with  one  of  the  interesting  features  of  the 
Atari  ST:  sovmd.  After  exploring  the  sound  capabilities  of  the  ST,  the 
book  moves  on  to  the  AEiS,  the  second  portion  of  GEM.  Prom  this 
point  on,  the  programs  you  see  will  have  very  few  VDI  functions  in 
them.  You  should  understand  the  VDI  and  how  it  works.  Now  move  on 
to  making  some  noise. 


CHAPTER  EIGHT 


Sound  Off! 


So  far  you  have  gone  through  the  VDI  and  looked  at  all  its  features. 
Now  we  pause  from  GEM  and  look  at  some  of  the  features  of  the  Atari 
computer  itself.  The  piimaiy  focus  of  this  chs^ter  is  the  sound  output 
capabilities  of  the  Atari.  The  chs^ter  starts  with  some  background  on 
sound  and  how  it  is  generated.  Then  some  sound  circuitry  and 
machine  capabilities  are  discussed.  Next  you  look  at  some  com- 
ponents used  to  create  sound  on  the  Atari.  Finalty.  you  develop  a 
sound  program  that  demonstrates  the  various  capabilities  of  the 
machine 


What  b Sound? 


Sound  is  a wave.  From  the  physics  point  of  view,  it  is  called  a 
mechanical  wave,  which  means  that  some  physical  object  is  vibrat- 
ing. For  example,  sotmd  waves  cause  small  pulsations  in  the  air.  When 
the  pulsations  move  through  the  air  and  reach  your  ear,  thqr  cause 
your  eardixun  to  vibrate  as  well.  Tire  brain  receives  the  signals  from 
the  ear  and  interprets  them  as  sound. 

A waveform  looks  very  much  like  the  waves  on  the  open  ocean. 
Figure  8-1  depicts  a sample  waveform  with  the  vertical  axis  measur- 
ing the  amplitude  of  the  wave  and  the  horizontal  axis  measuring 
time:  Note  that  several  attributes  of  the  wave  have  been  labeled.  TTie 
period,  or  cycle,  is  the  time  it  takes  for  the  wave  to  complete  one 
repetition.  The  period  measured  in  Figure  8-1  shows  the  wave  start- 
ing at  amplitude  0 with  a positive  slope  (that  is,  a slope  that  moves 
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upward).  The  wave  goes  up  and  then  down  back  to  amplitude  0 (but 
now  with  a negative  slope)  and  goes  down  and  back  up  to  complete 
the  cycle. 


1 ptfiod  or  oyolo 


Figure  8-1  Waveform  Conqionents 


Amplitude  measures  how  high  the  wave  travels  above  the  center 
line.  In  general,  waves  with  greater  amplitude  contain  a greater 
amotmt  of  power.  We  all  know  that  laige  ocean  waves  can  certainly 
do  more  damage  than  small  ones!  In  relation  to  soimd,  the  same  rule 
applies:  loud  noises  have  a greater  amplitude  than  soft  noises. 

Frequency  Is  another  Important  component  of  the  wave.  It  Is 
usually  measured  In  cycles  per  second  (also  called  hertz,  abbreviated 
as  Hz).  The  frequency  measures  the  niimber  of  cycles  completed  In  a 
given  time.  In  the  waveform  shown  In  Flgiu^  8-1.  the  wave  goes 
through  two  cycles  In  one  second,  “nierefore.  its  frequency  is  two 
hertz.  Note  the  relationship  between  the  period  and  the  frequency, 
the  period  is  the  number  of  seconds  per  cycle  while  the  frequency  Is 
the  number  of  cycles  per  second.  As  the  units  suggest  the  perlcxl  Is 
simply  the  inverse  of  the  frequency  and  vlc:e-verseL  Thus.  If  the 
frequency  Is  veiy  high,  jrou  know  that  there  must  be  many  periods 
each  second,  which  meems  that  the  period  Is  veiy  smetll.  In  the  case 
of  a wave  with  a frequency  of  1000  hertz,  for  example,  each  cycle  has 
a period  of  one  1/ 1000th  of  a second. 

How  does  this  relate  to  soimd  on  the  Atari  ST?  The  only  way  the 
Atari  can  produce  sound  Is  through  a speaker,  which  produces  sound 
ly  vibrating.  The  rate  at  whicdi  the  speaker  vibrates  determines  the 
frequency  of  the  sound.  Increstsed  frequency  corresponds  to  Increased 
pitch.  For  example,  the  note  A above  middle  C has  a frequency  of  440 
hertz.  This  Is  the  note  used  by  concert  orchestras  for  tuning  the 
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instruments.  The  next  octave  above  occurs  at  double  that  frequency, 
or  880  hertz.  The  computer  needs  some  mechanism  to  drive  the 
speaker  at  whatever  frequency  is  desired. 


Making  the  Circuit 

The  electric  sound  circuitry  in  the  Atari  ST  is  based  on  the  AY-3-8910 
Programmable  Sound  Generator  (PSG)  made  by  the  General  Instru- 
ment Corporation.  This  microchip  interfaces  with  the  rest  of  the 
computer  emd  allows  you  to  specify  frequencies  and  volume  in  a pro- 
gram, and  generates  the  output  to  vibrate  the  speaker.  The  PSG  can 
produce  a different  sound  on  three  Independent  voices.  It  is  capable  of 
producing  either  noise  (like  static)  or  a tone  (like  musical  notes).  You 
can  select  any  voice  and  any  tone-noise  combination  you  desire.  You 
can  have  any  one  voice  producing  a tone,  or  noise,  or  both.  Each  voice 
has  independent  volume  control  which  can  either  be  set  at  a constant 
level  or  fluctuate  in  a pattern. 

The  PSG  has  16  registers  numbered  0 through  15.  E)ach  register 
controls  a particular  sound-producing  attribute  (see  Figure  8-2). 
Registers  0 and  1 control  the  frequency  of  voice  A,  registers  2 and  3 
control  the  frequency  for  voice  B,  and  registers  4 and  5 control  the 
frequency  for  voice  C.  Register  6 is  the  noise  period.  Register  7 is  the 
voice  enable  register,  which  selects  which  voices  are  on  and  the  type 
of  output  for  each  voice.  Registers  8,  9,  and  10  control  the  volumes 
for  voices  A B,  and  C,  respectivefy.  Registers  11,  12,  and  13  control 
the  envelope  period  and  type  of  envelope  for  the  volume  pattern. 
Registers  14  and  15  are  input  and  output  ports  between  the  PSG  and 
other  components  of  the  ^tem.  Since  the  Atari  ST  uses  these  ports 
for  sensitive  system  operations,  we  do  not  deal  with  them. 

Setting  the  Voice  Period  Registers 

The  hrst  six  registers  control  the  frequency  of  the  output  for  the  three 
voices.  Each  voice  requires  two  registers  to  hold  the  v^ue  that  selects 
a frequency.  The  actual  value  held  in  these  registers  is  not  the 
frequency  but  rather  the  period  of  the  tone.  The  period  consists  of  a 
12-bit  value,  where  the  four  high  bits  numbered  8 through  1 1 go  in 
the  coarse  tune  register  for  the  voice,  and  the  eight  low  bits  go  into 
the^ne  tune  register  (see  Figure  8-2).  (Remember  that  bit  num- 
bering starts  at  0 and  goes  from  right  to  left)  To  determine  the  period 
of  a frequency,  convert  the  frequency  into  a period,  and  then  split  the 
period  into  the  two  register  values.  You  know  from  the  discussion 
above  that  the  period  is  the  Inverse  of  the  frequency.  That’s  fine  for 
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Register 


Use 


Bit  Number 

b7ib6ib5ii>4it>3ib2i  bilbo 


Voice  A Tone  Period 


Fine  Tune 


iliiljliliillllii  Coarse  Tune 


Voice  B Tone  Period 


Fine  Tune 


Coarse  Tune 


Voice  C Tone  Period 


Fine  Tune 


ijnsn 

iliiil 


Ipiil 


Coarse  Tune 


Noise  Period 


lifniiiliiiiiij 


HiHli 


5- bit  value 


Voice  Enable 


In/Oui^  Noise  Tone 


iobIioa  C 


B 


AC 


B 


8 


Voice  A Volume 


giii-il 


Env 


4-bit  val  ue 


Voice  B Volume 


.... 


Env 


4-  bit  val  ue 


10 


Voice  C Vol  ume 


»!!!•:!!!!!!!!!!! 

jiiiiiiiiljijijj 


Env 


4- bit  value 


1 1 


12 


Envelope  Period 


Fine  Period  Value 


Coarse  Period  Value 


13 


Envelope  Shape /Cucle 


1 4- bit  Cycle 


14 


I/O  Port  A Data 


8- bit  data  value 


15 


I/O  Port  B Data 


8- bit  data  value 


Figure  8-2  General  Instniment  AY-3-8910  RegistieiB 


humans,  but  the  PSG  needs  an  adjusted  period  value  because  the 
timing  of  the  chip  is  driven  by  an  electrical  signal  called  the  clock 
input  The  clock  input  is  supplied  at  a constant  frequency,  and  the 
output  frequency  you  want  heard  must  be  adjusted  by  the  frequency 
of  that  clock  input  The  frequency  of  the  clock  input  is  2 MHz.  or  2 
million  cycles  per  second.  This  frequency  is  used  to  synchronize  all  the 
components  in  the  ^tem.  The  sound  chip  uses  1/16  of  the  clock 
input  so  that  you  must  divide  2 MHz  by  16. 

Given  a particular  output  frequency  (f),  you  can  determine  the 
period  (p)  for  this  frequency  by  the  following  equation: 

p=l/f  (1) 

To  determine  the  tone  period  (TP)  used  by  the  PSG,  simply  multiply 
the  period  from  equation  1 the  clock  adjustment 


TP  = p * (2  MHz  / 16) 


(2) 
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By  combining  the  two  preceding  equations  you  get  a single  equation 
that  given  the  frequency  yields  the  tone  period  for  the  PSG  tone 
registers  to  use.  This  equation  is  as  follows: 

TP  = 2 MHz  / (16  • f)  (3) 

For  example,  if  you  want  the  PSG  to  produce  the  tone  for  A above 
middle  C,  plug  the  frequency  of  440  Hz  into  equation  3. 

TP  = 2000000  Hz  / (16  • 440  Hz)  = 284.09091 

Because  the  PSG  does  not  accept  fractional  values,  the  tone  period 
for  a frequency  of  440  Hz  is  284. 

At  this  point,  you  have  a value  that  can  be  represented  as  a 12-bit 
binary  number.  Now  you  need  to  split  this  value  into  the  coarse  and 
fine  tune  registers.  From  a mathematical  standpoint  the  coarse  tune 
register  represents  increments  of  256  because  in  the  binary  number- 
ing ^tem  bit  8 represents  values  of  2*  or  256.  Therefore,  the  coarse 
tune  raster  value  (CT)  is  the  tone  period  divided  by  256  (to  get 
increments  of  256),  and  the  fine  tune  register  value  (FT)  is  the 
remainder.  The  equation  for  this  is: 

TP  = 256  CT -H  FT 

From  this  equation,  you  can  write  C statements  to  calculate  the 
coarse  and  fine  tune  register  values  as  follows: 

CT  = TP  / 256; 

FT  = TP  % 256: 

where  all  variables  are  of  an  Integer  type.  In  the  interest  of  efficiency, 
the  C statements  to  use  in  your  programs  would  look  like  this: 

CT=(TP>>8)&0x0F; 

FT  = TP  & OxFF. 

The  first  statement  shifts  the  tone  period  bits  to  the  right  ty  eight  bits. 
This  eliminates  the  fine  tune  portion  of  the  tone  period.  The  bit-wise 
AND  (&)  with  QxOF  ensure  that  onty  the  low  four  bits  of  the  coarse 
time  value  are  used.  In  the  second  statement  only  the  low  eight  bits 
are  needed;  therefore,  a bit-wise  AND  (&)  with  QxFF  is  used. 

Contlnulr^  with  the  example  above,  you  have  a tone  period  of  284 
to  place  into  the  coarse  and  fine  tune  registers.  The  value  for  the 
coarse  tune  register  is  the  integer  result  of  284  divided  by  256,  which 
is  1.  The  fine  tune  register  holds  the  remainder  of  this  division  here 
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equal  to  28.  Therefore,  to  get  a tone  of  440  Hz  output  by  the  sotmd 
chip,  the  value  28  must  be  placed  In  the  fine  tune  register  and  the 
value  1 in  the  coarse  tune  register.  Once  you  have  set  the  tone  period, 
you  are  ready  to  produce  the  sound. 

Noise  Period 

Register  6 determines  the  period  of  the  noise.  Since  this  raster  uses 
only  five  of  the  eight  bits  available  to  it,  there  are  32  different  noise 
frequencies  available.  Note  that  because  this  register  stores  the  period 
of  the  wave,  a higher  value  means  a lower  frequency.  For  the  PSG  on 
the  Atari  ST,  the  frequency  output  ranges  from  4 kHz  to  125  kHz. 

Envelope  Generation 

What  is  the  envelope?  An  envelope  can  be  used  to  control  the  volume 
of  a voice.  The  PSG  has  an  envelope  generator  that  does  this.  There 
are  two  attributes  to  an  envelope:  shape  and  period.  The  envelope 
shape  control  register,  register  13,  uses  the  lower  4 bits  to  determine 
the  shape  of  the  envelope.  Figure  8-3  shows  the  various  values  that 
can  be  placed  in  this  register  and  the  resulting  waveform. 

The  top  of  the  waveform  represents  maximum  volume  and  the 
bottom  no  volume.  For  example,  the  first  waveform  shown  in  Figure 
8-3  starts  at  the  highest  volume  and  decreases  to  the  lowest  volume. 
The  time  required  for  this  single  iteration  of  the  waveform  is  called 
the  envelope  period.  The  envelope  period  is  set  using  registers  11 
and  12.  Register  12  is  an  eight-bit  coarse  period  value  for  the  envelope, 
and  register  1 1 is  an  eight-bit  fine  period  value. 

The  process  of  determining  the  envelope  period  value  is  similar  to 
the  process  used  for  calculating  the  tone  perlcxl.  First  you  must 
decide  how  long  you  want  the  envelope  to  last  (measured  in  seconds). 
This  will  be  the  basic  period  (ep).  The  actual  envelope  period  (EP)  used 
in  the  registers  must  also  be  adjusted  for  the  timing  rate  Just  as  the 
tone  period  is  adjusted.  However,  the  envelope  perlcxl  uses  a timing 
adjustment  value  of  2 Mhz  divided  by  256.  Therefore,  the  equation 
for  calculating  the  envelope  perlcxl  is  this: 

EP  = (2  Mhz  / 256)  • ep 

For  example,  if  the  envelope  period  is  to  be  1/2  of  a second,  the 
envelope  period  is  as  follows: 

EP  = (2000000  cycles/sec  / 256)  • 0.5  sec  = 3906.25 

Sinc«  the  coarse  tune  register  measures  increments  of  256,  the 
value  for  the  coarse  tune  register  is  3906  divided  256,  which  is  15. 
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Values  for 

Envelope 

Shape/Cycle 

Shape  # Waveform  Shape  Register 


1 

\ 

0 through  3 

2 

/I  _ . . 

4 through  7 

3 

8 

B 

\ 

9 

10 

6 

\1 

11 

B 

AAAAAAAAAAA 

m 

8 

/ 

13 

9 

BSSBSBBBSBag 

14 

10 



15 

J L_  Envelope  Period 

1 1 (duration  of  one  cycle) 

Pigare  8-3  Envelope  Waveform  Shapes 


The  fine  tune  roister  is  the  remainder  of  this  division,  which  is  66. 
Therefore,  to  get  an  envelope  period  of  1/2  of  a second,  you  place  15 
into  register  12  and  66  into  roister  1 1. 

Note  that  in  Figure  8-3  waveforms  1,  2,  4,  6,  8,  and  10  are  only 
active  for  one  period.  After  that  the  volume  value  is  either  aU  on  or 
all  off.  The  other  waves  are  (^clic  and  keep  repeating  at  one  envelope 
period  The  waveforms  shown  in  the  figure  are  the  only 

waveforms  available  based  upon  the  bit  settings  In  register  13.  The 
actual  function  of  each  bit  is  not  important  because  all  combinations 
are  shown  here. 
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Volume  Control 

Roisters  8,  9,  and  10  control  the  volume  levels  for  voices  A.  B.  and 
C,  respectively.  The  low  four  bits  (bits  0 through  3)  control  the 
constant  volume  level  for  the  associated  voice.  Because  there  are  four 
bits,  there  are  16  different  volume  levels.  The  value  15  is  the  highest 
volume,  and  value  0 is  the  lowest  (off).  Bit  4 in  these  registers 
activates  the  envelope  volume  control.  If  bit  4 Is  set  to  1,  the  volume 
for  that  voice  is  controlled  the  current  envelope  settings.  If  bit  4 
is  0,  the  volume  is  controUed  by  the  value  in  the  volume  control 
register.  Therefore,  to  activate  the  envelope  control,  place  the  value  16 
into  the  volume  control  register. 

Sound  Output 

To  activate  the  speaker,  you  must  do  two  steps.  First  enable  the  voice 
or  voices  to  be  output  Then  set  the  volume  for  the  voice  or  voices. 
Enabling  the  voice  output  is  done  through  register  7,  aptly  called  the 
voice  enable  roister.  Hils  register  is  designed  as  an  inverse  regis- 
ter, which  means  that  the  bit  values  have  the  reverse  interpretation 
to  usual.  Thus,  a bit  set  to  1 is  said  to  be  “off,"  and  a bit  set  to  0 is 
said  to  be  “on.” 

Looking  at  Figure  8-2,  you  see  that  the  voice  enable  register  has 
three  parts:  the  tone  enable,  the  noise  enable,  and  the  Input/output 
control.  The  Input/output  control  is  associated  with  bits  6 and  7. 
These  bits  control  data  flow  in  to  and  out  of  registers  14  and  15.  As 
mentioned  earlier,  these  registers  are  not  used  in  this  book.  The  tone 
enable  portion  of  register  7 is  located  in  bits  0,  1,  and  2.  These  bits 
turn  on  tone  output  for  voices  A.  B.  and  C,  respective^.  Bits  3,  4.  and 
5 are  the  noise  enable  bits  for  voice  A,  B,  and  C,  respectively. 

If  the  tone  enable  bit  is  set  to  0 (this  is  an  inverse  register),  the 
tone  specified  In  the  coarse  and  fine  tune  register  for  that  voice  is 
output  For  example,  if  bit  0 is  set  to  0,  the  tone  for  voice  A is  output 
at  the  volume  indicated  In  register  8.  If  bit  0 and  bit  2 are  both  0, 
the  tones  for  voice  A and  for  voice  C are  output  at  their  correspond- 
ing volume  levels. 

The  noise  enable  bits  work  in  the  same  manner.  If  bit  3 is  0,  noise 
is  output  on  voice  A at  the  indicated  volume.  The  noise  used  for  the 
voice  is  specified  in  register  6.  This  is  the  only  register  used  for  noise 
output  Therefore,  all  voices  always  have  the  same  noise  output  at  any 
given  time. 

Note  that  any  channel  or  combination  of  voices  czm  produce  both 
noise  and  a tone  at  the  same  time.  For  example,  if  3^u  want  to  output 
a tone  at  440  hertz,  the  value  28  must  be  placed  in  register  0 and  the 
value  1 in  raster  1.  The  register  8 must  be  set  to  a nonzero  value 
(15  is  the  loudest),  and  register  7 must  have  the  value  62  (blnaiy 
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111110).  This  enables  voice  A to  produce  the  tone.  If  you  put  the 
value  54  (binary  110110)  into  raster  7,  noise  and  tone  are  output 
on  voice  A 


Program  SOUTiDEMO 

The  program  SOUNDEMO  demonstrates  the  use  of  the  PSG.  This  is 
a menu-driven  program  that  allows  the  user  to  choose  from  a variety 
of  sound  effects  and  also  allows  direct  access  to  the  PSG  registers  so 
that  the  user  can  experiment  with  different  sounds.  SOUNDEMO  also 
demonstrates  several  other  features,  such  as  the  alpha  mode  of  the 
VDI,  which  has  not  yet  been  covered.  The  VDI  is  primarily  designed 
for  graphics  output  However,  since  many  programs  use  much  text  it 
would  be  veiy  inefficient  for  the  program  to  format  text  strings  and 
output  them  as  graphic  text  The  alpha  mode  of  the  VDI  is  used  so 
that  the  Atari  screen  can  emulate  a standard  text-based  terminal. 
Alpha  mode  provides  many  of  the  terminal-type  functions  such  as 
cursor  positioning,  screen  dearing  to  the  end  of  the  line  or  to  the  end 
of  the  screen,  line  insert  and  ddete  and  cursor  positioning. 

SOUNDEMO  also  shows  how  to  access  restricted  portions  of 
memoiy.  For  the  program  to  work  properly,  it  must  ensure  that  the 
keydick  feature  is  disabled.  This  is  done  by  checking  one  of  the 
reserved  system  memoiy  locations,  disabling  the  keydick  bit  in  that 
value,  and  replacing  the  value  in  the  memoiy  location.  When  the 
program  finishes,  the  kqrdick  is  restored  to  its  Initial  state  (either  on 
or  off).  This  tystem  variable  is  located  in  a restricted  portion  of 
memoiy  and  must  be  accessed  with  a special  procedure. 

Looking  at  ni^( ),  jrou  can  see  the  control  flow  of  the  program  (see 
Listing  8-1).  After  performing  the  usual  initialization,  the  program 
turns  off  the  keydick  by  using  the  set_keyclick( ) routine.  The  next 
step  sets  the  workstation  to  alpha  mode  using  the  v_enter_cur( ) 
command.  The  program  then  enters  a do-loop  that  controls  the 
display  of  the  menu.  First  v-cnriiomet ) is  called  to  send  the  cursor 
to  the  home  position,  which  is  the  upper  left  comer  of  the  screen. 
The  v-eeosf ) function  dears  from  the  current  cursor  position  to  the 
end  of  the  screen.  The  menu  is  then  displayed.  There  are  seven  sound 
effects,  an  option  for  custom  sounds,  and  a sdectlon  that  uses  the 
Do8onnd( ) function.  Finally,  there  is  an  exit  option.  A second  do-loop 
is  entered  to  allow  the  user  to  make  and  verify  a selection.  If  the 
sdectlon  is  0 (exit  selection),  the  program  breaks  out  of  the  inner  loop 
and  goes  back  to  the  outer  loop.  If  the  sdectlon  is  not  0,  the  program 
calls  the  appropriate  function.  If  the  selection  is  not  valid,  the  sdec- 
tlon is  set  to  —1  (using  the  default  option  of  the  C switch  com- 
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T .taring  8-1  Program  SOUNDEMO 

SDUNDCnO.C  Sound  testing  program 

This  program  demonstrates  the  uses  of  the  sound  chip. 


System  Header  Fiies  & Constants 

ft  »««««)(« )HI »««««««»)!««««  «««««»»«/ 


tSinciude 

<5tdio.h> 

✓ft 

Standard  ID 

^include 

<osbind.h> 

✓ft 

GEMDQS  routines 

ttinciude 

<gemdefs.h> 

✓ft 

GEM  structures 

ttinclude 

<obdefs.h> 

✓ft 

GEM  ur  ite  modes 

^include 

<ctype.h> 

✓ft 

character  macros 

ttdefine  FRLSC  0 

ttdefine  TRUE  IFRLSE 

/ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 

GEM  Rppiication  Overhead 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft/ 

Deciare  giobai  arrays  for  VDI. 

typedef 

int  I40R0; 

✓ft 

UORD  is  16  bits 

I4DRD 

contri[12]. 

✓ft 

VDI  controi  array 

intout[12B],  intin[128]. 

✓ft 

VDI  input  arrays 

ptsin[12B],  ptsout[128]; 

✓ft 

VDI  output  arrays 

I40RD 

screerLJvhandie, 

✓ft 

virtual  screen  workstation  ^ 

screen^handle. 

✓ft 

physical  screen  workstation 

screen— rez. 

✓ft 

screen  resolution  0,1,  or  2 

coior— screen. 

✓ft 

flag  if  color  monitor 

X— max. 

✓ft 

max  X screen  coord 

y-jnax; 

✓ft 

max  y screen  coord 

char 

con term; 

✓ft 

console  status  byte 

/ftftftftftftftftftftftftllftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft 

Rppiication  Specific  Data 

ftftftiiftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft/ 

✓ft  Sound  register  names 
char  *reg_name[]  = { 

"Voice  R Fine  Tune", 

"Voice  R Coarse  Tune*, 

"Voice  6 Fine  Tune", 

"Voice  B Coarse  Tune", 

"Voice  C Fine  Tune", 
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UstiiigS'l  (continned) 

"Voice  C Coarse  Tune", 

"Noise  Period", 

"Mixer  Selection", 

"Voice  P Volume", 

"Voice  B Volume", 

"Voice  C Volume", 

"Envelope  Period  Fine  Tune", 

"Envelope  Period  Coarse  Tune", 

"Envelope  Shape^Cycle" 

Sound  chip  instructions.  To  urite  data  into  a sound  register,  use 

* function  6iaccess(dat,  reg.j^um  | 0x60)  uhere  dat  is  the  data 

* to  write  and  reg_num  is  the  register  number.  The  following 

* defines  set  the  write  bit  for  use  with  GiaccessO  (i.e.  PFINE 

* puts  data  into  register  0).  Note:  DO  NOT  write  directly  into 

* the  mixer  register,  use  function  mixer()  (see  text  for  the 

* explanation. 


ttdefine 

PFINE 

0 1 

0x80 

ttdefine 

PCOPRSE 

1 1 

0x80 

ttdefine 

BFINE 

2 1 

0x80 

ttdefine 

BCOPRSE 

3 1 

0x60 

ttdefine 

CFINE 

4 1 

0x80 

ttdefine 

CCDPRSE 

5 1 

0x80 

ttdefine 

NOISEPER 

6 1 

0x80 

ttdefine 

MIXER 

7 1 

0x80 

ttdefine 

PVOL 

8 1 

0x80 

ttdefine 

BVOL 

9 1 

0x80 

ttdefine 

CVOL 

10 

1 0x60 

ttdefine 

ENVFINE 

11 

t 0x60 

ttdefine 

ENVC0PR5E 

12 

t 0x80 

ttdefine 

ENVCYCLE 

13 

1 0x80 

y*  Channel  output  selection  (in  octal).  Use  bitwise  PND  (&)  to 
combine  channels,  then  use  the  mixer()  function. 

ttdefine  TONEP  076 

ltdefine  TONEB  075 

ttdefine  TONEC  073 

ttdefine  NOISEP  067 

ttdefine  NOISEB  057 

ttdefine  N0I5EC  037 

Bdeflne  PLLOFF  077 

char  soundLjdemo[  ] = { 

play  note  P (440  Hz)  for  2 seconds 
0,  2B,  1,  1,  7,  62,  8,  8,  130,  100,  7,  63, 

play  chord  of  P,  CIS.  E for  2 seconds 
0,  2B,  1,  1,  2,  194,  3,  1,  4,  123,  S,  1,  7,  56, 

8,  8,  S,  8,  10,  8,  130,  100,  7,  63, 
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listing  8>1  (oontinned) 

"Ramping"  sound  effect 

0,  0,  1,  1,  7,  G2,  0,  B,  12B,  1,  129,  0,  1,  255,  7,  G3,  255,  0 


GEM- related  Functions 


UQRO  open_vuork(physJiandle) 

UQRO  phys^andle; 

Function:  This  function  opens  a virtual  workstation. 

Input:  physJiandle  ° physical  workstation  handle 

Output:  Returns  handle  of  workstation* 

{ 

WORD  work-in[ll], 

uork_jDUt[57], 

neuuhandie;  handle  of  workstation 

int  1 ; 


for  (1  = 0;  i < 10;  i++) 
uork_in[l]  = 1; 
work_in[10]  = 2; 
neu^andle  = physJiandle; 


sot  for  default  values 

use  raster  coords 

USB  currently  open  ukstation 


v_opnvuk( work-in,  &new_handle,  uorl<^ut); 
v^lrwk(new_handle) ; clear  workstation 

return(nBu-handle) ; 


6et^creen-attr(  ] 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen^vhandle. 

Output:  Sets  x_max,  y_fnax,  color^creen,  and  screen-rez. 

< 

UORD  work_out[57] ; 

vq-jBxtnd(screen.vhandle,  0,  workjout); 
x^ax  = work_out[0]; 
y_max  = uorkjout[l]; 

screen_rez  = Getrez();  ^ b low,  1 = med,  2 = high 

color^croen  = (screen_rez  < 2);  mono  2,  color  0 or  1 

> 


Application  Functions 
« KIHf  »«»4flfft«  ft  ««««»»  ft  ««««»««  if 


Sound  Off!  195 


Listing  8-1  (continned) 

SBt_contBrm( ) 

Function:  SBts  Rtarl  5T  global  varlablo  location  0x464 
Input:  VarlablB  contorm  must  bo  SBt  to  now  v/aluB 

Output:  NonB. 

NotBs:  This  function  MUST  bB  callBd  using  supervisor  mode, 

B . g . , SupBxec  ( SB  t^on  term ) 

{ 

<^(char  «)0x464  = conterm; 
return; 

> 


gBt^onterm( ) 

Function:  Gets  value  of  Rtarl  ST  global  variable  location  0x464 
Input:  None. 

Output:  None.  Sets  variable  conterm. 

Notes:  This  function  (1UST  be  called  using  supervisor  mode, 

e.g.,  Supexec(getuconterm) 

< 

conterm  = *(char  *)0x464; 
return; 

1 


se  tJ<eyc  1 1 cl<  ( se  1 1 1 ng ) 

Int  setting; 

Function:  Provide  access  to  key  click  setting. 

Input:  setting  = TRUE  to  turn  on 

FRLSE  to  turn  off 

Output:  Returns  current  setting  of  key  click. 

Notes:  Uses  functions  set^cnterm()  and  get^onterm() 

II IHI  «««««««  »««««««« 1HH(  «««««««  »«««««« 

char  save.jcon; 

Supexec(get^onterm) ; 

save-Con  = conterm:  save  current  settings 

If  (setting) 

conterm  = save^on  | 1;  key  click  on 

else 

conterm  = saveucon  & 0xfe;  key  click  off 

Supexec  ( set^onterm ) ; 
return(save_con  & 1); 

> 


y*  bit  0 Is  key  click  setting  *y 
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Listing  8-1  (continued) 

ualt(m8) 
long  ms; 

Punction:  Provide  delay  for  sound  effects  routines. 

Input:  ms  = delay  in  milliseconds. 

Output:  None. 

Notes:  Because  the  routine  is  implemented  in  C.  The  delay 

is  only  approximate.  The  inner  loop  takes  1 ms. 

««««««««««««  «««««« IMMHIKIHHIlHflHHHIKIHHHHIlf « KIHHIlf/ 

{ 

long  i; 

for(;  ms  > 0;  ms--) 

for  (i  = 125;  i > 0;  i--) 

e 

return; 

> 


mixer(ch) 
int  ch; 

Function:  Sets  mixer  register  in  sound  chip. 

Input:  ch  s integer  value  to  put  in  register. 

Output:  None.  Register  7 set. 

««««««««« 

< 

register  temp; 


temp  = Glacces8(0,7) ; 

/« 

temp  = temp  ) 077; 

✓» 

ch  = ch  1 0300; 

Glaccess( temp  & ch,  MIXER); 

✓* 

return; 

> 


read  current  value 

turn  off  current  mixer  setting 

set  bits  6,7  to  prevent 

changing  of  1^0  bits 

urite  neu  setting 


clear.jsound( ) 

Function:  Sets  sound  registers  to  0. 

Input:  None. 

Output:  None.  Turns  off  ail  sound  generation. 

{ 

register  i; 


fcr(l  =0;  i < 7;  i++) 

6iacces8(0,  i | 0x80); 

mixer (ftLLOFF);  handle  reg  7 separately 

6 1 access (0,  PVQL); 

61 access ( 0 , BVOL ) ; 

6iaccess(0,  CVOL); 
return; 
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UstingS*!  (continued) 

enterjnot08( ) 

Tunction;  Rlious  usgp  to  enter  sound  registers  from  the  keyboard - 
Input:  Nona. 

Output:  None. 

< 

int  reg,  input  register 

dat;  register  data 

ciear_sound(); 

for(;;)  loops  until  neg  reg  entered 

{ 

u^urhomeC  screei\.uhandl  e ) ; 
v-Beo8(8creerL.uhandle) ; 
printf( 'Current  values:'^n" ) ; 

for (reg  = 0;  reg  <=  13;  reg++)  display  registers 

printfCac2d>  »-30s  »4o\n", 

reg,  reg^ame(reg] , (6iacces8(0,  reg)  & 0377)); 
printf ( "^n" ) ; 

printf( 'Enter  register  number  to  change^n'); 
printf('or  a negative  value  to  end:  '); 
scanfC^d',  &reg); 

if  (reg  < 0)  neg  reg  ends  function 

{ 

clear_sound( ) ; 
return; 

> 

prlntf( "Enter  data  to  store:  '); 
scanfCa^o',  &dat);  get  data 

if  (reg  ==  7)  if  mixer,  user  mixer() 

mixer(dat); 

else  if  (reg  <=  13)  else  urite  data 

6iacces8(dat,  reg  | 0x80); 
ignore  all  else 

> 

> 

8iren( ) 

Function:  Sound  effect  for  European  siren. 

Input:  None. 

Output:  None. 

{ 

printf ( 'NnPress  any  key  to  stop:Nn'); 
ciear^ound( ); 

mixer(TONER);  set  tone  output  on  channel  fl 

6iacce8s(15,  RVOL);  set  max  volume  on  R 

do 

< 
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Listing  8-1  (continued) 

Giaccess(254,  PFINE); 
Giaccess(0,  RCORRSE); 
uait(350L); 
Giaccsss(8G,  RFINE]; 
Giaccess(l,  RCORRSE); 
uait(350L) ; 

} uhlle  ( !CconlG( ] ) ; 
clear^cund( ) ; 

Craucln( ) ; 
return; 


set  higher  tone  on  fi 

wait  350  ms 

set  lower  tone  on  fl 

wait  350  ms 

check  if  any  key  pressed 
turn  off  sound 
capture  key  pressed 


gunshot ( ) 


Function:  Sound  effect  for  gunshot. 
Input:  None. 


Output:  None. 


{ 

clear^oundC ) ; 

6iaccess(15,  NOISEPER); 
fflixer(NOISER  & NOISEB  & NOISEC); 
Giaccess[16,  RVOL); 

Giaccsss(16,  BVQL); 

6iaccess(16,  CVOL); 

Giaccess(16,  ENVCORRSE); 
Giaccess(0,  ENVCYCLE); 
return; 

> 


set  max  noise  period 
sot  noise  on  all  channels 
set  volume  to  be 
controlled  by  envelope 
generator 

set  envelope  period 
set  cycle  type 


expiosion( ) 


Function:  Sound  effect  for  explosion. 
Input:  None. 

Output:  None. 


< 


clear^ound( ) ; 

Giaccess(B,  NOISEPER); 
mixer(N0I5ER  & NOISEB  & NOISEC); 
6iaccess(16,  RVOL); 

Giaccess(16,  BVOL); 

6iaccess(16,  CVOL); 

6iaccess(56,  ENVCORRSE); 
6iaccess(0,  ENVCYCLE); 
return; 


set  noise  period 
noise  on  all  channels 
envelope  control  on 
all  channels 

envelope  period 
cycle  type 


laser( ) 

Function:  Sound  effect  for  laser. 
Input:  None. 

Output:  None. 
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Listing  8-1  (continued) 

{ 

register  sueep; 


> 


printf ( 'NnPress  any  key  to  stop.Sn'); 
clear^ound(  ] ; 

mixer ( TONER] ; use  channel  ft  tone  only 

6iaccess(15,  fiVOL);  set  max  v;olume 

do 


{ 


for  (suaep  = 48;  sueep  <=  70;  sueep+-i‘] 


{ 

61 access (sueep,  REINE) 
uait(3L] ; 

> 

} uhile  ( !Cconis( ] ) ; 

G 1 access ( 0 , RVOL ] ; 

Craucin( ] ; 
return; 


decreasing  tone  sueep 
; on  channel  fi 
3 ms  delay 

y*  check  for  keypress  *y 
y*  turn  off  sound  *y 
y*  capture  key  *y 


bomb( ] 

Function:  Sound  effect  for  bomb. 

Input:  None. 

Output:  None. 

( 

register  sueep; 

clear^ound( ) ; 

mixer(TONEfl) ; y*  tone  on  channel  fl  *y 

6iaccess(i5,  PVOL];  y*  max  volume  *y 

for  (sueep  = 46;  sueep  <=  160;  sueep-«-+) 

{ y*  decreasing  tone  sueep  *y 

Giacces8( sueep,  PFINE]; 
ualt(25L) ; 

> 

explosion();  y*  end  effect  *y 

return; 

} 


uhistle( ) 

Function:  Sound  effect  for  uhistle. 
Input:  None. 

Output:  None. 

{ 

register  sueep; 
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Listing  8'1  (continaed) 

clear^ound( ) ; 

6iacce88(l,  NOISEPER); 
mixer (TONER  & NOISES); 
Glacce88(15,  RVOL); 
61acce88(9,  8V0L); 
for(sueep  s 64;  sueep  >=  32; 
{ 

Glacc088( sweep,  PFINE); 
ualt(20L) ; 

} 

Glaccess [ 0 , PVOL ) ; 
ualt(150L) ; 

Giacces8(15,  PVOL); 
for(sueep  = 60;  sueep  >s  46; 
{ 

Glaccess (sueep,  PFINE); 
ualt(35L): 

} 

for (sueep  - 48;  sueep  <-  104 

Glaccess (sueep,  PFINE); 
ualt(15L); 

> 

clear^ound( ) ; 
return; 


set  noise  period 
set  channel  output 
max  vol  on  P 
lesser  uol  on  8 
sweep-- ) 

Increasing  tone  sueep 


stop  tone  sound 
ualt 

restart  tone  sound 
sueep-- ) 

Increasing  tone  sueep 


sueep+d-) 

/*  decreasing  tone  sueep 


/*  end  sound 


racR_nar( ) 

Function:  Sound  effect  for  race  car. 

Input:  None. 

Output:  None. 

< 

register  sueepf,  fine  register  sueep 

sueepc;  coarse  register  sueep 


clear^ound( ) ; 
Glacces8(6,  8C0PRSE); 
Glacce8s(15,  8FINE); 
mlxer(T0NEP  & TONEB) ; 
Glacces8(15,  PVOL); 
Glacces8(10,  BVOL): 
for (sueepc  = 10;  sueepc 
{ 


>=  5; 


set  B tone  ualue 

tones  on  P and  B 
max  woiume  on  P 
/*  lower  volume  on  6 *>' 
sueepc--) 

Increasing  tone  on  P 


Glacce88(sueepc,  PCOPRSE) ; 
for(sueepf  = 255;  sueepf  >s  0;  sueepf--) 
{ 


> 


Glaccess (sueepf,  PFINE) 
ual t(2L) ; 
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UstiiigS-l  (contlnaed) 

> 

for(sueepc  = 8;  sueepc  >=  3;  sueepc--) 

{ increasing  on  at  higher  tone 

6i access ( sueepc , 8C08R5E ) ; 
for(sueepf  = 255;  sueepf  >=  0;  sueepf — ) 

< 

6iacce88(sueepf , RFIKE); 
uait(4L) ; 

> 

> 

for (sueepc  = 6;  sueepc  >=  2;  sueepc — ) 

{ increasing  on  fl  higher  still 

G i access ( sueepc , RCORRSE ) ; 
for (sueepf  = 255;  sueepf  >s  0;  sueepf 

{ 

Giaccsss (sueepf,  RFINE); 
uait(GL) ; 

> 

> 

cIear_sound( ) ; end  sound  effect 

return; 

> 


Main  Program 


mainn 

{ 

int  ap^d; 
int  select; 


application  inlt  verify 
menu  selection 


WORD  gr_uchar,  gr_hchar,  values  for  VDI  handle 

gr^box,  gr^box; 

int  key,. click;  save  key  click  setting 


Initialize  GEM  Recess 


ap^d  = appl^nitO;  Initialize  RES  routines 

if  (ap^d  < 0)  no  calls  can  be  made  to  RES 

{ use  GEMDOS 

Cconus(****>  Initialization  Error.  <»*»^n*); 

Cconus(  *Pres8  any  key  to  continue. '*^n" ); 

Craucln( ) ; 

8xlt(-l);  set  exit  value  to  shou  error 


> 
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Listing  8-1  (continued) 

screeri^handie  = Get  handle  for  screen 

grafjiandle(&gr^char,  &gr_hchar,  &gr_wbox,  &gr^box); 
screarL-v/handle  = apen.v/uorl<(8creerL4}handle) ; 
set_screenLjattrC ) ; Get  screen  attributes 

Pppllcatlon  Specific  Routines 

turn  off  key  click 
key_click  = set^eycl  icl<(  FALSE ) ; 

v^nter^ur(screen_v/handiej ; use  alpha  mode 

do 

< 

v_xurhome  ( screeru.uhandle ) ; 

v^eos(8cre8n_vhandle) ; clear  screen 

prlntf ( '^nNn^nNnSound  Demonstration  Program^nNnNn" ) ; 

printfC  1>  European  Slron^n"); 

printf("  2>  GunshotNn"); 

prlntfC  3>  Explosion^n* ); 

prlntf("  4>  Laser^n"); 

prlntf ( • 5>  Falling  Bomb^n*); 

prlntf("  6>  Whlstle^n'); 

prlntf (■  7>  Race  Car^n"); 

prlntf (■  0>  Enter  Your  Ounvn"); 

prlntf ("  9>  DosoundO  DemoNn"); 

printfC  0>  Exit  ProgramNn^n" ) ; 

do 

< 

prlntf ( "Enter  your  selection:  "); 
scanf(”^d",  ^select); 

If  (select  ==  0) 

break;  exit  loop 

sultch  (select) 

< 

case  1:  slren(); 

break; 

case  2:  gunshot(); 

break; 

case  3:  exploslonO; 

break; 

case  4;  laser(); 

break; 

case  5:  bomb(); 

break; 

case  6:  uhlstle(); 

break; 
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Listing  8*1  (continued) 


case  7: 

racH  -car  ( ) ; 

case  8: 

break; 

enter^otes( ) ; 

case  9: 

break; 

Dosound ( 8ound_demo ) 

default: 

break; 

select  = -1; 

break; 

> 

y while  (select  < 0); 

} while  (select  !=  0);  end  do  loop 

Program  Clean-up  and  Exit 


/*  Ualt  for  keyboard  before  exiting  program 


setJ<eycllck(key-cllck) ; 
u^xit^ur(screen^vhandle) ; 
u^lsuuk(screeru.v/handle) ; 
appl^xltO; 


restore  key  click  */ 
exit  alpha  mode 
/*  close  workstation 
/*  end  program 


mand)  and  the  loop  Is  repeated  requesting  another  selection.  When 
the  sound  functions  return,  the  Inner  loop  Is  exited  and  the  outer 
loop  displays  the  menu  again.  When  the  exit  selection  Is  requested, 
the  outer  loop  exits,  the  keydlck  state  is  restored,  and  ▼_eslL.ciir( ) 
is  called  to  exit  the  alpha  text  mode  of  the  workstation.  Then  the 
workstation  is  closed  and  the  program  is  finished. 

Protected  Memory  Access 

In  the  application  functions  section  of  the  program,  look  at  the 
set_k^click( ) routine.  Its  one  parameter  determines  whether  the 
keydlck  is  turned  on  or  off.  If  the  parameter  is  TRUE,  the  kQrdick  is 
turned  on.  If  it  is  FALSE,  the  keydlck  Is  turned  off.  The  setJke3rclick( ) 
function  returns  the  setting  of  the  keydlck  before  it  is  changed.  The 
first  statement  in  8et-ke]rclick( ) is  a function  that  provides  the 
special  access  mentioned  above.  This  is  needed  because  the  current 
setting  of  the  keydlck  is  located  in  a protected  section  of  memoiy.  A 
standard  program  does  not  have  access  to  this  location  in  memoiy 
so  an  error  would  occur  if  the  program  tried  to  read  it  To  gain  access 
to  this  memoiy,  the  program  needs  to  set  the  microprocessor  into 
what  is  called  supervisor  mode.  This  allows  the  program  to  access 
virtually  any  location  in  memoiy.  The  Supexec( ) function  is  one  of 
two  functions  that  can  be  used  to  put  the  processor  into  supervisor 
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mode.  Supexec( ) Is  an  extended  BIOS  function  that  places  the  proces- 
sor into  that  mode  and  executes  the  code  starting  at  the  address 
specified  by  its  parameter.  In  set_lceycllck( ).  the  parameter  is  the 
address  of  the  function  ^t_contmn( ).  When  Siqiexecf ) is  called,  the 
processor  is  set  to  supervisor  mode  and  get_c<mterm( ) is  executed. 
When  get_conterm( ) is  done,  the  processor  is  reset  to  user  mode  and 
set-keydickf ) continues.  Another  function  can  be  used  to  set  the 
processor  to  supervisor  mode  called  St^erf).  This  is  a GEMDOS 
function  that  also  has  one  parameter:  the  address  for  the  stack 
location.  Once  Snperf)  is  called,  the  processor  stays  in  supervisor 
mode  until  another  call  to  Stqterf ) is  made.  The  difference  between 
the  two  functions  is  that  Siq>esec( ) does  not  allow  BIOS  or  GEMDOS 
calls.  It  is  slmpty  a quick  means  to  allow  access  to  protected  locations 
without  wonying  about  stacks  and  modes. 

Function  get_contenn( ) slmpfy  reads  memoiy  location  hexadecimal 
0x484  into  the  global  variable  conterm.  Location  0x484  contains  the 
console  settings.  Appendix  D shov^  a set  of  addresses  that  are  “cast 
in  stone”  in  the  memoiy.  Specified  by  the  Atari  ST  designers  these 
locations  are  guaranteed  not  to  change  through  future  revisions  to 
the  ST.  Your  programs  can  obtain  and  change  the  information 
regarding  the  ST  Itself  by  reading  and  writing  to  these  locations  in 
supervisor  mode.  Many  of  these  values  are  better  left  imchanged, 
however. 

In  set-ki^clickf ),  once  the  current  console  settings  are  retrieved, 
the  kq^ck  setting  is  saved  in  the  variable  save-con.  If  the  requested 
new  setting  is  TIIUE,  the  program  wants  the  keyclick  setting  turned 
on.  The  previous  console  settings  aie  bit-wise  ORed  with  the  value  1 
because  bit  0 contains  the  keyclick  setting.  By  using  the  bit-wise  OR 
with  the  value  1,  bit  0 is  set  to  1 regardless  of  its  previous  value.  On 
the  other  hand,  if  the  kqrclick  Is  to  be  turned  off,  the  current  value 
in  save..con  is  bit-wise  AJNDed  with  hexadecimal  FE.  This  sets  bit  0 
to  0 and  leaves  all  other  bits  unchanged.  After  the  new  console  setting 
has  been  determined,  Siq>C3Eec( ) is  called  again  to  set  the  new  setting. 
Function  set-contennf ) stores  the  value  in  variable  conterm  at  the 
appropriate  location.  V^en  set_conterm( ) is  finished,  control  returns 
to  set_keyclick( ),  which  returns  the  previous  setting  of  the  keydlck. 

The  reason  the  keyclick  must  be  turned  off  for  this  program  Is  that 
the  keyclick  feature  also  uses  the  sound  chip  to  produce  the  clicking 
sounds.  This  would  interfere  with  the  use  of  the  chip  by  the  program. 

Now  look  at  function  walt( ).  This  function  simply  provides  a delay 
when  it  is  called.  The  loop  in  the  function  provides  an  approximate 
one  millisecond  (1/1000  second)  delay.  The  parameter  determines  the 
approximate  number  of  milliseconds.  Walt( ) is  used  in  several  loca- 
tions to  produce  some  of  the  sound  effecte. 
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PSO  Access 

Access  to  the  sound  chip  is  provided  through  the  XBIOS  function 
Giacces8( ),  which  has  two  parameters.  The  first  is  the  value  to  be  put 
in  the  register;  the  second  is  the  register  to  use.  If  the  register 
parameter  has  a value  between  0 and  15,  Giaccess( ) performs  a read 
of  that  register  and  returns  the  current  value.  If  the  register  number 
is  bit-wise  ORed  with  the  value  0x80  hexadecimal  (that  is,  has  its 
high  bit  set),  Glaccess( ) writes  the  value  of  the  first  parameter  into 
the  roister.  In  the  j^pllcation-specific  data  section  of  SOUNDEMO, 
there  is  a set  of  defined  constants  that  list  the  14  registers  to  be  used 
(AFINE,  ACOARSE,  BFINE,  BCOAI^E,  and  so  on).  These  constants 
specify  the  writing  mode  for  function  GiaccessO  and  are  used  to 
provide  more  readable  code. 

The  next  set  of  defined  constants,  TONEA  TONEB,  TONEC,  NOISEA 
NOISEB,  NOISEC,  and  ALLOFF,  are  the  bit  setting  for  register  7,  the 
voice  enable  register.  Note  that  these  constants  are  octal  values.  Use 
the  bit-wise  AND  to  create  any  combination  of  tone  and  noise  on  any 
of  the  voices.  For  example,  if  you  want  tone  on  voice  A and  noise  on 
voice  C,  use  the  value  TONEA  & NOISEX).  Remember  that  register  7 
is  an  Inverse  register  so  the  bit-wise  AND  is  used  instead  of  the 
bit-wise  OR 

Register  7 controls  the  mix  of  sounds  produced  by  the  sound  chip. 
This  register  also  controls  the  Input  and  output  through  registers  14 
and  15.  When  setting  the  bits  in  the  voice  enable  register,  also  called 
the  mixer  register,  you  do  not  want  to  alter  the  settings  of  bits  6 and 
7.  Therefore,  when  changing  the  voice  enable  bits,  you  must  first  read 
the  current  setting  in  roister  7,  change  the  voice  enable  bits  while 
retaining  the  settings  for  bits  6 and  7,  and  place  the  new  value  into 
roister  7.  If  you  do  not  do  this,  you  may  alter  the  data  flow  through 
the  PSG  and  cause  the  ^tem  to  stop  woridng. 

To  facilitate  the  protection  of  bits  6 and  7 in  the  mixer  register, 
function  mizer( ) Is  provided  in  SOUNDEMO.  This  function  has  one 
parameter,  which  is  the  voice  selection  value  to  be  placed  in  the  mixer 
register.  Function  mixerf ) first  reads  the  current  value  in  register  7 
into  variable  temp.  AU  voices  are  tinned  off  by  setting  the  low  six  bits 
to  1 through  the  bit-wise  OR  with  octal  value  077.  Next  the  parameter 
di  has  its  high  bits  set  to  1.  Then  the  variables  ten^  and  ch  are 
bit-wise  ANDed  together.  Variable  temp  holds  the  current  bit  settings 
for  the  I/O  ports  and  ch  holds  the  bit  settings  for  the  voice  mix.  When 
ANDed  together,  the  result  is  a single  value  with  the  proper  I/O  port 
and  mixer  bit  settings.  For  example,  temp  is  set  to  the  binary  value 
abllllll,  where  a and  b are  the  bit  settings  for  bits  6 and  7.  The 
variable  ch  is  set  to  the  binary  value  Iluvwxyz,  where  the  letters 
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Stand  for  the  voice  mix  bit  settings.  When  ANDed  together,  you  get 


abllllll 
& Iluvwxyz 

abuvwxyz 

so  that  the  port  settings  are  not  changed  and  the  mixer  settings  are 
set  to  their  new  values. 

The  next  fimction  in  SOUNDEMO,  clear-80und( ).  simply  dears  the 
sound  registers  so  that  all  soimd  generation  is  stopped.  The  function 
goes  through  registers  0 through  6 and  sets  them  to  0.  It  sets  the 
mixer  register  to  ALLOFF.  The  volume  for  each  chemnel  is  then  set  to 
0.  Technically,  to  turn  off  a channd,  its  volume  must  be  set  to  0. 
According  to  the  PSG  documentation,  simpfy  disabling  the  voice 
using  the  mixer  register  does  not  actually  turn  that  channel  off. 
Although  no  sound  may  be  coming  out  the  channel  is  still  active  and 
the  PSG  is  still  processing  it 


Using  Ous  PSG 

Function  enter_notes( ) corresponds  to  selection  number  8 on  the 
menu,  entitled  “Enter  Your  Own.”  This  function  dears  the  screen  and 
displajrs  the  current  values  for  rasters  0 through  13.  TTie  user  is 
then  allowed  to  enter  a register  number  and  a value  to  place  in  that 
register.  If  a negative  register  number  is  requested,  the  function  exits. 

The  first  step  in  enter-notesf ) is  to  dear  the  soimd  registers  using 
the  deaT-80und( ) function.  Next  an  infinite  loop  is  entered,  which 
has  the  same  purpose  as  the  outer  control  loop  in  function  main( ). 
Within  this  loop,  the  function  dears  the  screen,  di^lays  the  current 
values,  and  requests  a raster  number.  If  the  register  number  is 
negative,  the  sound  registers  are  deared  again  and  the  function 
returns  to  the  calling  procedure.  If  the  register  number  is  not  n^ative, 
data  is  requested.  Once  the  data  is  entered,  the  function  checks  if  the 
register  number  requested  is  register  7.  If  so.  function  mlxerf ) is  used 
to  store  the  data.  Otherwise.  Glacoessf ) Is  used  to  store  the  new  value. 
If  a register  number  greater  than  13  is  entered,  the  data  is  ignored. 
The  infinite  loop  keeps  repeating  this  procedure  until  a n^ative 
register  number  is  entered.  The  current  sound  register  values  are 
listed  in  octal  because  octal  is  easier  to  use  in  this  case,  particularly 
for  roister  7.  The  scanff ) function  requests  the  register  number  as 
a dedmal  value  and  the  data  as  an  octal  value 
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The  Sound  Stage 

The  next  set  of  functions  is  the  sound  effect  functions  listed  In  the 
menu.  The  first  function  Is  function  siren( ).  This  function  emulates 
the  European  emergency  vehicle  siren,  which  is  a high  tone  followed 
by  a low  tone.  This  sequence  repeats  over  and  over.  The  first  step  for 
sirenf ) is  to  clear  the  sound  registers  using  dear-soundf ).  Only  one 
voice,  voice  A,  will  be  used  for  this  effect  so  that  the  mixer  is  set  to 
output  a tone  on  voice  A and  the  voice  is  set  for  maximum  volume. 
A do-loop  is  used  to  produce  the  repeating  sequence  of  tones.  First 
the  tone  period  of  the  higher  note  is  set  emd  the  function  waits  for 
350  milliseconds  (about  1/3  of  a second).  While  the  program  is  wait- 
ing, the  sound  chip  is  producing  the  specified  sound.  After  the  waiting 
period,  the  lower  tone  is  set  and  another  350-millisecond  wait  occurs. 
The  loop  then  repeats  until  a key  is  pressed.  When  a key  is  pressed, 
the  soimd  chip  is  cleared  and  the  value  of  the  key  press  is  captured 
using  the  CrawdnO  call.  The  function  then  returns  to  the  calling 
procedure.  It  is  important  to  capture  the  key  press;  otherwise  it 
remains  in  the  keyboard  buffer  and  appears  on  the  selection  line 
for  the  main  menu. 

Since  the  PSG  is  constantly  processing  the  current  register  set- 
tings, the  sound  chip  works  independently  of  your  program.  Once  the 
sound  registers  have  been  set,  that  sound  is  continually  produced 
until  the  sound  register  is  changed  or  the  volume  for  the  voices  is 
turned  off.  For  example,  in  siienC ) the  tone  continues  for  350  mil- 
liseconds while  the  program  is  in  the  walt()  function.  The  tone 
changes  ly  resetting  the  tone  period  values.  All  other  registers  eire 
unaffected.  In  the  case  of  an  envelope  setting,  as  soon  as  a new 
envelope  shape  is  selected  that  envelope  b^ins  to  cycle.  You  may 
change  tone  periods,  noise  periods,  volumes,  envelope  periods,  and 
envelope  shapes  at  any  time.  Any  change  you  make  ^ects  only  that 
register.  This  relieves  your  program  of  having  to  reset  the  sound 
registers  for  each  new  sound  3TOu  want  to  create. 

Function  gnnahotO  provides  a reasonable  facsimile  of  a gunshot 
sound  effect  This  function  utilizes  the  envelope  available  on  the 
sound  chip.  First  gnndiotf ) uses  clear-80und( ) to  clear  the  sound 
chip.  Then  the  noise  period  is  set  to  15  and  the  mixer  is  set  to  output 
noise  on  all  three  voices.  To  allow  the  envelope  shape  to  control  the 
volume,  the  volume  registers  for  the  three  voices  are  set  to  the  value 
16.  Next  the  envelope  coarse  period  value  is  set  and  the  envelope 
shape  is  chosen.  As  soon  as  the  envelope  sh£q)e  is  chosen,  the  PSG 
begins  cycling  through  the  envelope  (in  this  case  there  is  only  one 
cyde).  Thus  a gunshot  effect  is  heard. 

There  are  two  reasons  why  aU  voices  are  used  to  output  noise  for 
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the  gunshot.  First,  the  more  voices  used,  the  louder  the  soimd 
becomes.  Second,  the  noise  is  generated  by  very  short  random  tones. 
If  you  separate  the  noise  from  each  voice,  the  noise  from  each  voice 
may  sound  alike  but  it  is  not  exactty  the  same.  This  gives  the  gunshot 
its  piercing  texture. 

Function  explosion! ) is  veiy  similar  to  gimahot! ).  The  noise  has  a 
period  of  8 instead  of  15,  which  means  that  the  fr^uency  is  higher. 
The  coarse  envelope  period  for  ea^losion! ) is  longer,  so  the  sound  is 
of  longer  duration. 

Function  laser! ) uses  a sweep  effect  This  is  a constantly  increasing 
or  decreasing  tone,  which  causes  a continuous  changing,  or  “sweep- 
ing,” effect  Function  laser! ) uses  voice  A at  its  maximum  volume.  The 
fine  time  register  for  that  voice  A is  swept  from  a value  of  48  to  a 
value  of  70  with  a three-millisecond  delay  between  each  change.  This 
gives  quick  bursts  of  decreasing  tone  chiips.  Laser  continues  imtll  a 
key  is  pressed.  The  function  ends  by  turning  off  voice  A 

Function  bomb!)  uses  a combination  of  sound  effects.  First  is  a 
long  sweep  of  a decreasing-frequency  sound  !the  whistling  sound  of 
a falling  bomb)  that  ends  with  the  sound  of  an  explosion  created  by 
function  eq^tlosion! ). 

The  whistle! ) function  produces  the  “wolf*  whistle  that  a macho 
man  makes  toward  a pretty  female.  Function  ^rtiistle! ) uses  a com- 
bination of  tone  and  noise  since  a real  whistle  has  a slight  rushing 
air  sound.  The  tone  on  channel  A is  set  to  the  maximum  volume.  The 
noise  on  channel  B is  set  at  a lower  volume.  Then  the  fimctlon  goes 
through  two  increasing-frequency  tone  sweeps  and  then  a decreasing- 
frequency  tone  sweep. 

The  iace_car! ) fimctlon  emulates  the  sound  of  a race  car  that  is 
accelerating  and  shifting  gears.  It  uses  two  different  tones  on  two 
different  channels,  A and  B.  Channel  B contains  the  low,  grumbling 
sound  and  channel  A contains  the  increasing-frequency  sound.  Chan- 
nel A has  a higher  volume  than  channel  B.  The  function  goes  through 
three  different  sweeps  representing  the  three  different  gears.  Each 
loop  starts  channel  A at  a higher  frequency  than  the  previous  loop. 

Hie  Dosound! ) Function 

The  last  function  to  be  discussed  is  an  XBIOS  function  called 
Dosound! ).  It  is  called  in  case  9 of  the  switch  statement  Function 
Dosound! ) provides  and  processes  a sequence  of  sound  operations 
that  run  concurrently  with  your  program.  Thus,  while  Dosound! ) is 
generating  a sequence  of  sounds,  your  program  can  do  something 
else. 

The  parameter  for  Dosound! ) Is  a pointer  to  a sequence  of  bytes 
that  represent  the  settings  of  the  PSG  registers  and  time  delays  to  be 
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executed  between  each  byte  in  the  list  Under  the  application-specific 
data  in  the  program  the  last  variable  declared  is  the  character  array 
sonnd-demo.  Function  DosoundO  uses  pairs  of  bytes  to  set  the 
registers  of  the  PSG.  The  first  byte  is  a command  and  the  second  a 
data  value  (see  Table  8-1).  Command  numbers  from  0 through  15  are 
register  commands.  These  take  the  next  value  in  the  list  as  the  data 
to  be  stored  in  that  register.  For  example,  the  first  two  elements  in 
the  sound-demo  array  are  0 and  28.  This  places  the  value  28  Into 
register  0.  The  n»ct  two  values,  1 and  62.  indicate  that  the  value  62 
is  to  be  placed  in  register  1.  Then  the  value  62  is  placed  in  register 
7 and  the  value  8 into  register  8.  As  calculated  earlier,  the  value  28 
in  the  fine  register  and  1 in  the  coarse  register  corresponds  to  a tone 
at  440  Hz.  Placing  62  into  register  7 turns  on  tone  generation  for 
voice  A,  and  placing  8 into  register  8 turns  the  volume  on  half  way. 


Table  8-1:  Dosound(  ) Process  Commands 


Command  Number 

Function 

0 through  15 

Place  next  byte  Into  register. 

128 

Place  next  byte  Into  temporary  register. 

129 

Use  next  3 bytes  for  sweep  effect 
Byte  1:  raster  to  use. 

^rte  2:  Increment  value 
^rte  3:  teraiinatlon  value 
T^e  value  in  temporary  register  and  put  It  into 
raster  specified. 

Increment  register  by  increment  value  rmtll  It  equals 
the  termination  value 

130  through  254 

Use  next  byte  for  timing  delay  measured  in  1/50 
second. 

255 

If  next  byte  is  0.  terminate  the  Dosoundf  ) process. 
Otherwise,  use  value  for  timing  delay. 

Commands  130  through  255  take  the  next  value  in  the  list  as  the 
argument  and  use  this  value  as  a wait  period  before  moving  to  the 
next  command.  The  value  specifies  the  number  of  cycles  to  wait  based 
upon  a 50-Hz  clock  rate.  Therefore,  an  argument  of  50  causes  a delay 
of  one  second,  an  argument  of  25  causes  a delay  of  1/2  second,  and 
so  on.  Commands  128  and  129  are  used  together  to  produce  a sweep 
effect  Command  128  takes  the  next  value  in  the  list  and  places  it  in 
a temporary  register,  the  documentation  does  not  state  where  this 
register  is  located.  Corrunand  129  uses  the  next  three  values  as 
arguments  to  the  function.  The  first  argument  is  the  register  number 
to  use.  the  second  argument  is  used  as  the  increment  value,  and  the 
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third  argument  is  the  termination  value.  Command  129  takes  the 
value  in  the  temporary  register  (set  command  128)  and  places  it 
into  the  register  specified  by  the  first  argument  This  register  is 
incremented  by  the  Increment  value  of  the  second  argument  The 
sweep  stops  when  the  register  value  equals  the  termination  value  of 
the  third  argument 

The  contents  of  the  sound-demo  array  play  the  foUowing  sequence 
of  sounds;  first  the  note  A is  played  for  two  seconds,  then  a chord  is 
played  for  two  seconds,  and  a sweep  is  produced.  Toward  the  end  of 
the  first  line  in  the  sound-demo  array,  command  130  is  followed  by 
100.  This  causes  the  note  A (440  Hz)  to  be  played  for  two  seconds.  The 
last  command  on  the  first  line,  7 with  a data  value  of  63,  turns  the 
sound  off.  The  channel  is  not  turned  off.  Just  the  sound  output.  The 
next  set  of  commands  plays  a chord.  Note  A is  stored  in  the  voice  A 
tone  period  registers,  the  note  C-sharp  is  stored  into  the  voice  B tone 
period  registers,  and  note  E is  stored  into  the  tone  p>erlod  registers 
for  voice  C.  The  value  56  is  placed  into  register  7,  which  turns  on 
tone  output  for  all  three  voices.  The  value  8 is  used  as  the  volume  for 
each  voice  and  is  placed  into  registers  8,  9,  and  10.  The  command 
130  is  again  followed  by  the  value  100  to  create  a two  second  sound. 
Then  sound  generation  is  turned  off. 

The  last  section  produces  the  sweeping,  or  “ramping,”  effect  to 
demonstrate  commands  128  and  129.  First  a 0 is  put  into  register  0 
and  1 is  put  into  register  1.  Then  voice  A is  enabled,  and  the  volume 
is  set  Command  128  places  the  value  1 into  the  temporary  register. 
Command  129  has  three  arguments:  0,  1,  and  255.  When  command 
129  begins,  the  value  1 (from  the  temporary  register)  is  placed  into 
register  0.  This  register  is  Incremented  from  1 to  255.  At  this  point 
Dosonndf ) continues  with  the  next  Instruction  in  the  list  The  next 
command,  7 with  the  data  63,  disables  the  voices.  The  last  command, 
255  0,  is  the  termination  command  to  tell  Dosoundf ) that  no  more 
commands  are  to  be  processed.  This  causes  the  sovmd  output  to  stop 
and  the  end  of  the  Dosound( ) function. 

When  }rou  run  the  SOUNDEMO  program,  you  may  notice  that  when 
you  execute  the  falling  bomb,  whistle,  and  race  car  sounds,  the 
program  control  does  not  return  to  the  menu  until  the  sound  effect 
has  been  completed.  With  the  Dosound( ) demo,  Dosoand( ) plays  its 
note,  chord,  and  the  sweeping  effect  but  the  menu  is  redisplayed  while 
these  sounds  are  being  output  Thus,  with  the  Dosomtdf ) function, 
you  can  have  your  program  playing  a song  while  it  is  calculating  or 
displaying  something  on  the  screen.  The  Dosoundf ) function  is  effec- 
tive onfy  if  you  want  to  play  a sequence  of  tones  and  noises.  For  any 
lype  of  sound  effect  especial^  an  effect  that  requires  control  over  the 
sweep  time,  you  must  write  a function  for  the  sound  effect  that  uses 
the  Giaccess( ) function. 
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Play  around  with  SOUNDEMO  by  entering  your  own  values  into  the 
sound  chip.  You  should  also  try  to  make  your  own  sound  effects.  It 
can  be  fun! 

The  other  special  option  that  might  be  of  general  interest  to  you  is 
MIDI  ct^abillty.  MIDI  stands  for  Musical  Instrument  Digital  Interface. 
The  use  of  this  port  requires  an  understanding  of  the  MIDI  protocol 
and  hardware  interfacing.  Because  of  the  length  of  this  topic,  it  is  not 
covered  here.  However,  if  you  are  interested  in  communicating  with 
MIDI,  you  should  obtain  the  MIDI  specifications  document  Check 
with  your  local  music  store  about  this. 

The  remainder  of  this  book  discusses  the  use  of  the  AES.  The  AES 
provides  3«5ur  program  with  access  to  menus,  windows,  the  mouse, 
and  dialog  boxes. 


CHAPTER  NINE 

Application 
Environment 
Services:  The  AES 


Until  now  this  book  has  covered  one  of  the  major  components  of  GEM 
called  the  Virtual  Device  Interface  (VDI).  The  VDI  is  a device-indepen- 
dent method  for  producing  graphic  output  from  a program  to  any 
device.  In  this  chapter,  another  important  section  of  GEM  is  intro- 
duced— the  Application  Environment  Services  (AE:s).  You  can  see  how 
the  AES  works,  what  it  contains,  and  how  it  is  used. 


Introduction  to  die  AE^ 


By  now,  you  should  have  encountered  many  of  the  features  provided 
by  GEM  such  as  windows,  icons,  and  dialog  boxes.  The  AE:S  is  the 
portion  of  GEM  that  allows  your  program,  the  application,  to  Interact 
with  the  Graphics  Environment  Manager  (GEM).  The  AES  is  designed 
to  handle  all  user  interaction  with  the  desktop  and  desktop  objects 
in  selecting  an  item,  resizing  or  moving  a window,  moving  the  sliders 
of  a window,  or  choosing  a new  window.  All  these  operations  are 
handled  by  the  AE:S,  and  the  result  of  these  user  actions  is  reported 
to  the  current  application  program. 

AES  Components 

In  Cheqjter  1,  }rou  saw  that  the  AE^S  consists  of  five  main  pieces:  the 
menu/alert  buffer,  desk  accessory  buffer,  the  shell,  the  limited  multi- 
tasking kernel  and  dispatcher,  and  subroutine  libraries.  The 
menu/alert  buffer  is  simply  an  area  in  memory  that  the  AES  uses 
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when  handling  menus  and  alert  boxes.  When  a menu  or  alert  box  Is 
placed  on  the  screen,  It  may  cover  some  object  on  the  screen.  To  keep 
the  screen  neat  and  tidy,  the  Image  under  the  menu  or  alert  box  must 
be  replaced  when  the  user  has  finished  with  the  menu  or  alert  box. 
This  gives  the  Illusion  that  the  desktop  Is  a three-dimensional  sur- 
face. However,  since  the  screen  is  a two-dimensional  bit  msq),  once 
the  menu  or  alert  box  is  written  on  this  bit  m^  the  previous  contents 
are  lost  Therefore,  to  maintain  the  illusion,  the  A£^  saves  the  portion 
of  the  screen  that  is  covered  in  the  menu/alert  buffer.  Then  when  the 
menu  or  alert  box  is  no  longer  needed,  the  content  of  the  buffer  is 
copied  back  to  the  screen  bit  map,  which  restores  the  original  image. 
Since  the  size  of  this  buffer  is  one-fourth  the  size  of  the  screen 
memoiy  alert  boxes  and  menus  may  not  be  bigger  than  this. 

The  desk  accessory  buffer  is  a portion  of  memoiy  that  contains  the 
accessoiy  programs  listed  under  the  DESK  menu.  When  the  ^tem 
is  booted  (turned  on  or  reset),  any  files  on  the  disk  with  a file  lype 
of  “.ACC”  are  considered  to  be  desk  accessories.  These  files  are  loaded 
into  the  desk  accessory  buffer  and  can  be  accessed  throu^  the  Desk 
menu. 

The  shell  is  the  segment  of  the  AES  that  handles  the  execution  and 
termination  of  application  programs.  Any  time  a program  is  initiated, 
the  shell  takes  care  of  the  ^tem  initialization  to  start  running  the 
program.  When  the  program  is  finished,  the  sheU  handles  any  clean- 
up and  termination  procedures. 

The  limited  multitasking  kernel  and  dispatcher  consists  of  three 
different  parts:  the  desk  accessories,  the  screen  manager,  and  the 
dispatcher.  Multitasidng  slmpty  means  that  the  ^tem  can  run  more 
than  one  task  at  a time.  GEM  is  a multitasking  system.  The  dis- 
patcher divides  the  CPU  time  among  the  cuirentfy  executing  tasks: 
the  application,  the  desk  accessories,  and  the  screen  manager.  Tlie 
dispatcher  ensures  that  no  one  task  hogs  the  central  processor  and 
that  all  tasks  are  able  to  be  processed.  The  screen  manager  handles 
user  interaction  with  the  desktop.  Desktop  areas  include  the  border 
portion  of  an  active  window,  menu  selection,  and  any  portion  of  the 
desktop  not  inside  the  current  active  window  (such  as  icons  or 
selecting  another  window).  After  such  an  interaction  is  completed,  the 
screen  manager  informs  the  current^  running  application  of  the 
result  of  the  user  actions.  The  currently  running  Explication  is  the 
application  that  owns  the  current^  active  window  (the  topmost  win- 
dow). The  last  part  of  the  kernel  is  the  desk  accessories.  A desk 
accessoiy  is  an  Explication  that  supplies  some  handy  function  for  the 
user  and  usualty  performs  just  one  function.  Accessories  general^ 
don’t  use  the  menu  bar  and  require  only  a small  portion  of  the  screen, 
while  full  applications  use  the  entire  screen.  The  control  psinel  is  an 
example  of  a desk  accessoiy.  GEM  loads  up  to  six  accessories  when 
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it  is  booted.  The  dispatcher  allows  only  three  accessories  to  be  active 
(running)  at  any  one  time.  The  actual  number  of  desk  accessories 
loaded  into  your  system  depends  on  the  amount  of  memory  you  have 
and  the  size  of  the  accessories  themselves. 

AES  Definitions 

One  of  the  great  benefits  of  using  GEM  is  that  it  provides  a standard 
interface  for  all  programs.  Users  can  quickly  learn  a new  program 
because  most  of  the  operational  functions  such  as  sdectlng  menus, 
moving  the  cursor  with  the  mouse,  and  using  windows  are  the  same  for 
all  programs.  Programmers  don’t  have  to  worry  about  interfacing  with 
the  user  because  this  is  done  by  GEM.  To  fully  utilize  the  GEM  user 
interface,  you  need  to  understand  the  terminology  and  concepts  used 
in  the  rest  of  this  book.  The  section  below  provides  you  with  the 
definitions  3rou  need. 


Menus 

At  the  top  of  the  screen,  there  is  a line  of  terrt,  called  the  menu  bar 
which  provides  the  user  with  a set  of  operations  the  program  can 
perform.  For  example,  the  desktop  has  a menu  bar  that  lists  the  items 
Desk,  File,  View,  and  Options.  These  names  are  called  menu  titles. 
Each  title  refers  to  a set  of  menu  selections  that  perform  a particular 
function.  Under  the  Desk  title,  the  first  item  is  an  information  func- 
tion that  provides  information  to  the  user  about  the  program  cur- 
rentty  rurming.  The  second  item  is  a dashed  line.  The  remaining 
items  are  the  desk  accessories  available  to  the  user.  The  File  menu 
provides  the  user  with  fUe  activities  such  as  creating,  opening,  saving, 
and  possibly  deleting  files  on  the  disk.  The  File  menu  also  contains 
the  Quit  option  so  the  user  can  exit  the  program.  The  format  for  the 
Desk  and  File  menus  should  always  follow  the  format  listed  here.  This 
enables  the  user  to  find  these  basic  options.  Do  not  worry  about  the 
names  of  the  desk  accessories  to  Include  in  the  Desk  menu.  GEM 
hzmdles  this  aspect  of  the  menu  when  your  program  is  executed.  Any 
other  menu  titles  on  the  menu  bar  are  application-dependent  You 
may  create  as  many  menus  as  can  fit  across  the  screen.  Just  make 
sure  that  the  titles  accuratefy  describe  the  functions  contained  in  the 
menu. 

The  entries  in  the  menu  are  called  menu  items.  Menu  items  have 
a psutlcular  format  that  you  should  follow.  The  menu  item  is  a brief 
one-  or  two-word  command  indicating  the  function  to  be  performed. 
Optionally,  there  may  be  a character  to  the  left  of  the  menu  item 
description,  which  represents  the  key  on  the  keyboard  that  performs 
the  same  ftmction.  Usually  this  refers  to  a control  code  where  the  user 
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presses  the  Control  key  and  a letter  key  at  the  same  time.  For  example, 
your  program  might  have  a Q next  to  the  Quit  menu  Item,  meaning 
that  the  user  can  press  Control-Q  to  exit  the  program  Instead  of  using 
the  mouse  to  select  the  Quit  option. 

Menu  Items  can  have  a number  of  attributes.  When  a menu  item 
Is  shown  In  Its  normal  state,  it  Is  said  to  be  enabled.  When  It  Is 
displayed  at  only  half  intensity.  It  Is  disabled.  The  AE^  does  not  allow 
you  to  select  a disabled  item.  A menu  item  may  be  checked.  When  an 
item  is  checked,  there  is  a check  mark  in  the  leftmost  character 
position  next  to  that  item.  A checked  item  usually  indicates  an  active 
toggle.  For  Instance,  a text  editor  might  use  a checked  item  for  text 
justification.  When  justification  is  on,  the  check  mark  is  displayed. 
When  it  is  off,  the  check  is  not  displayed.  If  this  item  is  selected,  the 
check  mark  toggles  to  its  opposite  state,  that  is,  if  it  is  on.  it  goes  off 
and  vlce-versa. 


GEM  uses  three  types  of  boxes:  an  error  box,  a dialog  box,  and  an 
alert  box.  An  error  box  Is  used  by  a program  when  a system  error  has 
occurred  and  the  program  can’t  perform  Its  operation.  The  error  box 
has  a predefined  format  that  says  an  error  has  occurred  and  provides 
the  number  of  the  error. 

A dialog  box  is  a rectangular  box  on  the  screen  that  requests 
information  from  the  user.  The  Information  requested  can  be  a file 
name  or  a complex  data  entiy  screen  as  might  be  used  in  an  Inventoiy 
program.  The  actual  contents  of  a dialog  box  is  determined  by  the 
programmer.  An  example  of  a dialog  box  occurs  In  the  Options  menu 
of  the  desktop.  The  Set  Preferences  selection  causes  a dialog  box  to 
be  displayed  so  that  the  desktop  options  may  be  set 

An  alert  box  is  a special  form  of  dieilog  box.  It  advises  the  user  of 
some  pertinent  condition  and  allows  the  user  to  verify  a particular 
operation.  For  example,  if  you  are  editing  a program  and  tiy  to  read 
in  a file  that  is  too  large  for  the  editor  to  handle,  an  alert  box  appears 
to  indicate  the  problem.  The  box  may  have  options  to  choose  to 
alleviate  the  problem. 

Windows 

A window  is  something  that  must  be  very  familiar  by  now.  It  is  an 
area  of  the  desktop  that  provides  communication  between  the  ap- 
plication and  the  user.  The  window  consists  of  several  components. 
These  are  the  title  bar,  the  information  line,  close  box,  full  box,  move 
bar,  size  box,  up  arrow,  down  arrow,  left  arrow,  right  arrow,  vertical 
scroll  bar  and  vertical  slider,  horizontal  scroll  bar  and  horizontal 
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slider,  and  the  work  area.  When  you  are  at  the  desktop,  the  directories 
for  your  disks  are  held  in  windows.  You  can  look  at  these  for  examples 
of  the  window  components.  The  title  bar  is  the  area  of  the  window 
that  holds  the  directory  currently  being  shown.  This  will  usualfy  be 
something  like  “A;\”  or  “A:\”  followed  a subdirectory  name.  The 
Information  line  is  the  area  of  the  window  that  shows  the  number  of 
bytes  used  and  the  number  of  items  displayed  in  that  directory.  Both 
the  title  bar  and  the  information  line  can  hold  up  to  80  text  charac- 
ters. The  close  box  is  located  at  the  left  end  of  the  title  bar  and 
contains  the  small  black  box  with  the  white  X on  it  When  the  user 
clicks  the  mouse  inside  the  close  box  the  AES  tells  the  application 
that  the  user  has  requested  that  the  window  be  closed.  The  full  box 
is  at  the  right  side  of  the  title  bar.  It  has  a white  diamond  on  a black 
backgroimd.  When  the  window  is  at  its  ‘‘normal’’  size  and  the  full  box 
is  clicked,  the  window  expands  to  its  maximum  size  as  specified  by 
the  application.  If  the  full  box  is  clicked  again  the  window  returns  to 
its  original  size.  The  move  bar  occupies  the  same  area  as  the  title  bar. 
When  the  user  presses  and  holds  the  mouse  button  on  the  move  bar, 
the  AES  provides  a half-intensity  outline  of  the  window  and  allows 
the  user  to  drag  this  outline  to  any  location  on  the  screen.  When  the 
button  is  released,  the  AES  tells  the  £q>pUcation  of  the  new  requested 
window  location.  The  size  box  is  located  in  the  lower  right  comer  of 
the  window  and  has  a white  slash  on  a black  square.  When  the  mouse 
button  is  pressed  on  the  size  box,  the  AES  displays  a half-intensity 
outline  of  the  window  and  allows  the  user  to  change  the  size  and 
shape  of  the  window  by  dragging  the  outline.  When  the  button  is 
released,  the  AES  indicates  to  the  application  the  new  requested  size 
of  the  window. 

The  up  arrow  and  down  arrow  are  located  on  the  right  border  of 
the  window  and  are  indicated  by  corresponding  up  and  down  arrow 
figures.  When  either  arrow  is  clicked,  the  AE)S  Informs  the  application 
of  this  event  The  application  redraws  the  window  as  appropriate.  For 
exeunple,  consider  the  desktop  display  of  your  directories  in  the  text 
mode  (set  in  the  View  menu).  When  you  press  the  up  arrow,  the  listing 
moves  up  by  one  line.  The  down  arrow  moves  the  listing  down  one 
line.  In  the  icon  mode,  the  up  and  down  arrows  move  the  icons  up 
and  down  one  row  of  icons.  Since  one  row  of  icons  is  taller  than  one 
row  of  text  the  application  must  consider  what  is  being  dlspla}red. 
The  left  and  right  arrows  work  analogous^  and  move  the  window  to 
the  left  and  right  over  the  contents.  The  vertical  scroll  bar  and  slider 
are  in  the  area  located  between  the  up  and  down  arrows.  The  slider 
represents  the  relative  location  in  the  entire  file  of  the  contents 
currentty  shown  in  the  window  and  the  relative  size  of  the  window 
to  the  total  size  of  the  daftt  For  instance,  if  the  slider  is  at  the  bottom 
of  the  scroll  bar,  the  Information  in  the  window  is  the  very  end  of  the 
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data.  If  the  size  of  the  slider  is  two-thirds  of  the  total  length  of  the 
scroll  bar,  two-thirds  of  the  total  amount  of  data  is  being  displayed 
in  the  window.  When  the  user  clicks  the  colored  area  of  the  scroll  bar, 
the  window  moves  one  page  either  up  or  down  depending  on  whether 
the  user  clicks  the  area  above  or  below  the  slider,  respectlvefy.  When 
the  user  presses  the  mouse  button  while  located  on  the  slider  itself, 
the  user  can  drag  the  slider  anywhere  within  the  scroll  bar.  When  the 
button  is  released,  the  appropriate  section  data  is  displayed.  The 
horizontal  scroll  bar  and  slider  work  in  the  same  way  as  the  vertical 
scroll  bar  and  slider. 

The  work  area  is  the  area  of  the  window  where  the  data  is  displayed. 
It  is  essentially  the  part  of  the  window  not  covered  by  any  of  the 
components  listed  above.  The  work  area  is  the  only  required  portion 
of  the  window.  All  other  components  are  optional  When  a window  is 
created,  the  application  tells  the  AE^  what  components  are  to  be 
Included  in  the  window.  Whenever  the  AEJS  draws  the  window,  it 
draws  only  those  components  that  have  been  included  in  the  window. 

Messages  and  E>rents 

All  user  interactions  with  the  border  components  of  the  window  are 
handled  the  A£!S.  When  the  user  interaction  is  complete,  the  AES 
reports  the  results  to  the  application  using  a mechanism  called  a 
message  pipe.  A message  pipe  is  simply  a means  for  communication 
between  one  program  and  another.  For  example,  when  the  user 
requests  a window  closed  by  clicking  the  close  box,  the  screen 
manager  sends  an  appropriate  message  to  the  application  owning 
that  window.  When  a message  is  sent  to  an  £q>pUcation,  it  is  called 
an  event  An  event  controls  the  flow  of  the  application  programs. 
There  are  k^ixiard  events,  mouse  events,  mouse  button  events,  mes- 
sage events,  and  timer  events.  Any  one  of  these  can  occur  at  any  time. 
As  you  can  see,  the  application  essentially  just  sits  around,  waits  for 
one  of  these  events  to  occur,  and  then  acts  upon  it.  For  exeunple,  an 
application  such  as  the  desktop  waits  for  an  event.  When  it  receives 
the  message  that  the  window  is  to  be  closed,  the  screen  manager 
sends  a message  to  the  desktop.  The  desktop  receives  the  event 
determines  what  type  of  event  it  is,  gets  the  data  regarding  the  event 
eind  f>erforms  the  appropriate  action— namely,  closing  the  window. 

Libraries 

The  AES  provides  routines  to  handle  all  the  objects  described  above: 
menus,  dialog  boxes,  alert  boxes,  windows,  events,  and  so  on.  These 
routines  are  held  in  libraries  that  are  included  as  part  of  the  AES 
in  memoiy.  Th^r  are  accessible  to  all  applications.  Since  each  appllca- 
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tion  does  not  need  its  own  copy  of  these  routines,  memoiy  is  con- 
served and  the  applications  require  less  space  on  the  disk. 

The  routines  are  divided  into  libraiy  groups  such  as  an  event 
libraiy,  an  application  library,  a menu  libraiy.  an  object  libraiy,  a forai 
libraiy,  a graphics  libraiy,  and  a scrap  library.  Other  libraries  are  file 
selector,  window,  resource,  and  shell.  The  remainder  of  this  book 
looks  at  how  these  routines  are  used  within  an  application. 


Program  Resources 


Files  with  a file  type  of  “PRO”  are  program  files.  This  is  how  GEM 
knows  that  this  file  can  be  executed.  You  may  have  noticed  files  with 
a file  type  of  "JRSC”  that  have  the  same  file  name  as  a program  file. 
This  companion  file  is  called  a resource  file.  A resource  file  contains 
such  items  as  the  program’s  menu,  dialog  and  alert  boxes,  icons,  and 
any  other  grsqihlc  Images  that  the  program  uses.  Each  item  in  a 
resource  file  is  called  an  object  The  term  object  is  used  quite  loosely 
in  the  GEM  documentation.  The  word  object  is  a vague  reference  to 
anything  from  a simple  string  of  text  to  an  inventory  entry  form.  For 
example,  the  menu  title  Desk,  the  menu  title  File,  the  Quit  option 
under  the  File  menu,  and  the  icons  on  the  desktop  are  objects  and 
can  be  held  in  the  resource  file.  The  resource  file  holds  these  objects 
in  an  organized  fashion  to  make  them  accessible  to  your  application 
program. 

Otfect  Trees 

The  objects  are  organized  in  what  is  called  a tree  data  structure.  A 
tree  consists  of  one  object  linked  to  several  other  objects,  called  the 
children.  Any  child  may  have  children  of  its  own,  and  the  children’s 
children  can  have  children.  The  basic  premise  of  the  tree  is  that  any 
item  in  the  tree  can  have  0 or  more  children  and  0 or  1 parent  This 
is  the  structure  of  the  tree  used  in  the  resource  file.  Other  tree 
structures  exist  but  do  not  concern  us  here. 

Figure  9-1  shows  a tree  for  the  basic  menu  used  in  a program. 
Notice  that  only  one  object  has  no  parent  This  object  “Main  Menu,” 
is  called  the  root  The  root  is  used  as  the  starting  point  for  the 
entire  tree.  In  the  figure,  the  root  has  two  children,  “Desk"  and  “File," 
which  are  titles  In  the  menu  bar.  Object  File  has  one  child,  the  option 
“Quit”  Object  Desk  has  eight  children:  six  desk  accessories,  a place  for 
your  information  message,  and  a disable  dashed  line.  All  boxes  shown 
in  the  figure  are  considered  to  be  Individual  objects.  In  this  tree,  the 
objects  are  just  text  In  general,  any  mix  of  object  typ>es  may  be  in- 
cluded in  a sln^e  tree. 
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Flgiiie9>l  8anq>le  Menu  O^ect  Tree 


Figure  9-2  shows  an  example  of  a more  complex  resource  tree.  At 
the  desktop,  the  Options  menu  has  a Set  Preferences  Item.  When  this 
Item  Is  selected,  a dialog  box  appears.  The  resource  tree  of  Figure  9-2 
shows  the  tree  associated  with  this  dialog  box.  The  root  of  the  tree  Is 
the  Set  Preferences  dialog  box  Itself.  In  other  words,  the  root  object 
contains  Information  that  Informs  the  AES  that  the  tree  Is  to  draw  a 
dialog  box.  Each  of  the  text  lines,  “SET  PREFEREITCES,”  “Confirm 
Deletes:,”  “Confirm  Copies:,”  and  “Set  Screen  Resolution:”  are  text 
objects.  The  “OK”  and  “Cancel”  objects  are  exit  buttons.  You  can  press 
these  buttons  by  placing  the  mouse  over  either  one  and  pressing  the 
mouse  button.  They  are  caUed  exit  buttons  because  when  you  press 
either  one.  you  signal  that  you  want  to  exit  the  dialog  box  and 
continue  with  the  program.  The  OK  and  Cancel  buttons  are  children 
of  the  dialog  box. 

Three  invisible  boxes  are  children  of  the  dialog  box.  The  resource 
tree  can  hold  many  different  types  of  objects.  Invisible  box  1 Is  the 
parent  to  the  top  yes/no  button  combination  (see  the  dialog  box  on 
your  desktop).  Invisible  box  2 is  the  parent  to  the  bottom  yes/no 
button  combination,  and  the  third  Invisible  box  surrovmds  the 


Figure  9-2  Set  Preferences  Dialog  Box  Object  Tree 
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low/medium/high  button  selections.  E^ch  button  in  these  sets  of 
buttons  is  called  a radio  button.  Much  like  the  mechanical  buttons 
on  a car  radio,  onfy  one  button  fh>m  each  set  may  be  selected  at  a 
time.  For  example,  the  screen  resolution  may  be  set  onfy  to  low, 
medium,  or  high.  You  could  not  have  a low-medium  resolution  set 
Just  as  you  could  not  have  yes  and  no  confirmation  of  file  deletions. 
When  you  press  one  button,  the  AES  automatical^  deselects  any 
other  button.  The  AES  knows  which  buttons  belong  to  the  same  set 
because  radio  buttons  of  the  same  set  have  the  same  parent  Hence 
the  need  for  the  invisible  boxes;  each  set  of  radio  buttons  has  its  own 
parent 

Object  Structures 

Hie  OBJECT  Structure 

Figures  9-1  and  9-2  show  the  logical  arrangement  of  a tree.  This  is 
how  a hiunan  would  visualize  the  tree.  In  a progreun,  the  tree’s  layout 
and  information  about  each  object  must  be  represented  in  memory. 
In  GEM  this  is  done  through  the  use  of  several  C structures.  Each 
entry  in  the  tree  is  called  an  object  and  is  represented  by  a structure 
called  OBJECT  (see  Figure  9-3). 

typedef  struct  object  { 


MORD 

□b_next; 

WORD 

□bJiead; 

UDRO 

ob.tail; 

WORD 

□b_type; 

WORD 

ob^fXags; 

WORD 

ob_£tate; 

CHRR 

*ob_jspec; 

WORD 

ob^; 

WORD 

ob_y; 

WORD 

□b_uldth; 

WORD 
} OBJECT; 

obJielght; 

Figure  9-3  Ibe  OBJECT  Stiuctnxe 

To  represent  the  tree  in  memory,  all  the  objects  are  placed  in  an 
array.  Hie  OBJECT  structure  field  ob-next  holds  the  index  of  the 
object’s  next  sibling.  Therefore,  the  ob-next  held  of  the  SET  PREF- 
ERENCES object  in  Figure  9-2  has  the  array  index  for  the  Conhrm 
Deletes:  object  The  held  obLJiead  has  the  index  to  the  object’s  hrst 
child.  Thus,  the  ob.Jiead  held  of  the  Set  Screen  Resolution:  object  has 
the  index  for  the  Low  radio  button  object  The  obJail  hdd  for  the  Set 
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Screen  Resolution:  object  has  the  array  index  for  the  High  radio 
button  object  which  is  the  last  child  of  the  parent  Therefore,  one 
array  is  used  to  hold  all  the  objects  for  a particular  tree.  By  retrieving 
the  array  index  for  the  children  or  siblings,  your  program  can  traverse 
through  all  objects  in  the  tree. 

The  field  ob-z,  ob_y,  ob-widtit  and  obJieight  determine  the  place- 
ment and  size  of  the  object  on  the  screen.  All  values  are  measured  in 
pixels.  The  x and  y coordinates  are  relattve  to  the  object's  parents.  If 
the  object  is  the  root  the  coordinates  are  screen  coordinates.  For 
example,  if  the  root  object  of  the  dialog  box  has  x and  y coordinates  of 
(200,  100),  the  upper  left  comer  of  the  dialog  box  is  placed  at  screen 
coordinates  of  (200,  100).  Now  assume  that  the  SET  PREFERENCE'S 
object  has  x and  y coordinates  of  (20,  20).  The  string  “SET  PREFER- 
ENCES” is  placed  20  pixels  to  the  right  and  20  pixels  down  from  the 
upper  left  comer  of  the  dialog  box.  This  corresponds  to  screen  co- 
ordinates of  (220,120).  This  allows  you  to  move  the  root  object  to  any 
point  on  the  screen  and  have  all  its  contents  move  accordingly. 

The  obviate  field  contains  the  current  state  of  the  object  The  state 
of  the  object  determines  how  the  object  is  drawn  and  what  functions 
it  can  perform  depending  upon  what  the  object  represents.  The  states 
are  shown  in  Table  9-1  as  they  are  defined  in  header  file  obde&JL 


Table  9-1:  Direct 
State  Definitions 


Constant  Name 

Value 

NORMAL 

0X00 

SELECTED 

0X01 

CROSSED 

0X02 

CHECKED 

0X04 

DISABLED 

0X08 

OUTLINED 

0X10 

SHADOWED 

0X20 

The  NORMAL  state  indicates  that  the  object  is  drawn  using  the 
normal  foreground  and  backgroimd  colors.  The  SELECTED  state 
indicates  that  the  object  is  drawn  with  the  foreground  and  background 
colors  reversed.  CROSSED  tells  the  AES  that  an  'X'  is  to  be  drawn 
over  the  entire  object  as  if  it  were  crossed  out  CHECKED  says  that  a 
check  mark  is  drawn  at  the  leftmost  edge  (usually  used  for  text-based 
objects).  An  object  is  DISABLED  means  that  the  object  is  drawn  in  a 
half-intensity  mode.  OUTLINED  specified  that  an  outline  is  to  appear 
around  a boxed  object  (only  for  objects  in  boxes).  SHADOWED  indi- 
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cates  that  the  object  (again  usually  a box)  Is  drawn  with  a dropped 
shadow,  meaning  that  the  right  and  bottom  edges  are  slightly  thicker. 

As  you  can  see  in  Table  9-1,  each  object  state  indicates  a particular 
bit  setting.  Therefore,  various  states  can  be  combined  such  as 
CHEXDKED  £md  SELEICTED.  NORMAL  Is  when  all  bits  are  0 or  no 
states  are  active.  Of  course,  some  combinations  such  as  SELECTED 
and  DISABLED  do  not  make  sense  and  should  not  be  set  together.  A 
bit  is  considered  set  when  that  particular  bit  has  a value  of  1. 

The  ob-flag  field  of  the  OBJE^CT  structure  is  similar  to  the  ob-state 
field.  The  various  flags  indicate  the  particular  attribute(s)  set  for  the 
object  Table  9-2  lists  the  object  flag  definitions. 


Table  9-2:  Ol^ect  Flags 


Constant  Name 

Value 

NONE 

0X000 

SELECTABLE 

0X001 

DEFAULT 

0X002 

EXIT 

0X004 

EDITABLE 

0X008 

RBUTTON 

0X010 

LASTOB 

0X020 

ToucHExrr 

0X040 

HIDETREE 

0X080 

INDIRECT 

0X100 

The  NONE  flag  indicates  that  there  are  special  attributes  for  this 
object  SELEXDTABLE  says  that  the  object  may  be  selected,  usually 
indicating  some  kind  of  button  or  a box.  DEFAULT  is  a flag  for  the 
Form  library.  Usually  in  the  case  of  a dialog  box,  the  DEFAULT  flag 
is  attached  to  one  of  the  exit  buttons.  When  the  user  enters  a carriage 
return,  this  object  is  automatical^  selected  as  the  exit  object  Onfy^ 
one  DEFAULT  object  is  available  in  any  one  dialog  box.  The  EIXIT  flag 
indicates  to  the  Form  library  that  when  the  user  clicks  the  mouse  on 
this  object  the  exit  condition  has  been  achieved  and  the  Form  library 
exits  the  dialog  box.  EDITABLE  means  that  the  user  can  edit  the 
object  In  some  way  as  specified  within  the  application.  RBUTTON 
specifies  that  the  object  is  a radio  button.  LASTOB  is  a flag  that 
indicates  the  last  object  is  the  object  tree.  If  you  build  your  own  trees, 
you  should  use  this  flag.  If  you  use  another  program  to  build  your 
resource  files  (as  is  done  for  the  programs  in  this  book),  you  don’t 
need  to  worry  about  setting  this  flag.  TOUCHEIXIT  tells  the  Form 
library  that  when  the  user  clicks  this  object  the  form  is  completed 
and  can  be  exited.  HIDETREE  makes  this  object  and  all  Its  children 
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“invisible.”  There  are  a number  of  AES  routines  that  locate  or  draw 
objects.  If  the  HIDETREE  flag  is  set,  these  functions  are  not  able  to 
draw  or  locate  the  object  or  any  of  its  childrea  INDIREX^T  indicates 
that  the  value  of  the  ob.spec  field  is  a pointer  to  the  actual  ob-^spec. 
This  lets  you  change  the  ob.spec  field  by  changing  the  pointer 
instead  of  constructing  a new  ob_spec  field. 

The  obulype  field  of  the  OBJECT  structure  provides  the  ^e  of  the 
object  The  A£^  routines  use  this  type  information  when  processing 
the  object  For  example,  if  the  type  indicates  a box,  the  AES  draws  a 
rectangle.  If  the  type  is  a boxed  string,  the  A£^  draws  the  text  and 
encloses  it  in  a box.  Table  9-3  lists  the  defined  object  types  and  their 
values. 


Table  9-3:  Object  Types 


Constant  Name 

Value 

G-BOX 

20 

G-TEXT 

21 

G_BOXTEXT 

22 

GJMAGE 

23 

G-PROGDEF 

24 

GJBOX 

25 

G_BUTTON 

26 

G_BOXCHAR 

27 

GJSTRING 

28 

GJTEXT 

29 

G_FBOXTEXr 

30 

GJCON 

31 

G_TITLE 

32 

The  type  of  the  object  also  determines  the  contents  of  the  ob_spec 
field.  The  ob_.q>ec  field  may  contain  either  the  data  layout  shown  in 
Figure  9-4  or  a pointer  to  an  additional  information  structure.  Object 
types  G-BOX  G-IBOX  and  GJBOXCHAR  all  use  the  ob-spec  layout 
shown  in  Figure  9-4.  The  high  byte  of  the  high  word  contains  a 
character.  The  low  byte  of  the  high  word  contains  a border  thickness. 
The  low  word  contains  the  color,  writing  mode,  and  fill  pattern  for  the 
box. 

The  character  portion  of  the  ob_spec  field  is  used  only  by  type 
GJBOXCHAR,  which  is  a single  character  enclosed  in  a box.  The 
character  portion  contains  the  ASCII  value  (see  Appendix  C)  of  the 
character  to  be  displa}^.  The  border  thickness  applies  to  all  boxes. 
If  the  border  thickness  is  0,  the  thickness  is  0 and  the  box  is  invisible. 
If  the  border  thickness  is  a positive  value  from  1 through  127,  the 
thickness  is  measured  from  the  edge  of  the  box  inward.  Thus  the 
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Border  Text  Inside 
Color  Writing  Color 
Mode 


Figure  9-4  The  ob-spec  Field  Data  Layout 


outside  dimensions  of  the  box  remain  the  same  and  the  border  grows 
toward  the  center  of  the  box.  If  the  border  thickness  is  a negative 
value  from  -1  through  -127,  the  thickness  is  measured  outward 
from  the  objects  edge.  Although  it  is  not  mentioned  in  the  documen- 
tation, it  is  assumed  that  these  values  are  measured  in  pixel  units. 
The  colors  for  a particulau*  box  use  four  bits. 

The  writing  mode  of  the  ob-spec  field  is  a single  bit.  If  it  is  set  to 
0,  text  is  written  in  transparent  mode.  If  the  bit  is  set  to  1,  text  is 
written  in  replace  mode.  The  last  section  of  the  ob^pec  field  is  the 
fill  pattern.  The  fill  pattern  is  a 3-bit  value.  If  the  three  bits  are  all  0, 
the  fill  is  hollow.  If  three  bits  are  all  1 (evaluating  to  7).  the  fill  pattern 
is  a solid  fill.  Values  1 through  6 indicate  patterns  of  increasing 
darkness.  The  actual  patterns  used  depend  on  the  output  device  but 
the  increase  in  density  is  guairanteed. 

Object  type  G_BOX  simply  indicates  a graphic  box  that  may  have 
the  attributes  indicated  by  the  fields  in  the  object  structure.  Object 
G_BOXCHAR  is  a box  that  contains  one  character  of  text.  Object  type 
G-IBOX  is  considered  an  invisible  box.  The  fill  pattern  and  internal 
color  are  ignored.  The  color  and  border  thickness  may  be  used.  A 
border  thickness  of  0 makes  the  box  invisible.  One  purpose  of  an 
invisible  box  is  to  provide  a parent  for  a set  of  radio  buttons. 

Object  type  G_BUTTON  is  a graphic  text  object  centered  in  a box. 
Type  G_STRING  (no  comments  from  the  back  row,  please)  is  simply 
a string  of  graphic  text.  Type  G-TITLE  is  a text  string  used  in  menu 
titles.  Each  of  these  three  types  uses  the  ob-spec  field  as  a pointer  to 
a text  string. 

The  remaining  objects  require  more  information  than  can  be  stored 
in  the  OBJECT  structure.  In  these  cases,  the  ob-spec  field  is  used  as 
a pointer  to  a secondary  structure.  The  layout  of  the  secondary 
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structure  depends  upon  the  type  of  object  described.  These  additional 
structures  are  called  TEDINFO.  ICONBLK.  BITBLK.  APPLBLK,  and 
PARMBLK. 

The  TEDINFO  Structure 

Types  G-TEXT.  G_BOXTEXT.  G_FTEXT,  and  G-FBOXTEXT  aU  use 
the  obijipec  fidd  as  a pointer  to  a TEDINFO  structure  (see  Figure 
9-5).  The  TEDINFO  structure  Is  used  with  objects  that  have  editable 
text.  This  Is  text  that  can  be  altered  by  the  user  during  the  course  of 
the  program.  The  AEiS  routines  use  the  TEDINFO  structure  to  rdieve 
the  user  of  many  of  the  tasks  associated  with  data  entry.  The 
TEDINFO  structure  used  in  conjunction  with  the  AES  routines  can 
provide  automatic  data  entry,  data  validation,  default  values,  and 
format  templates. 

typedef  struct  taxt-Bdinfo  { 


char 

*te-ptext; 

char 

»tB,ptmplt; 

char 

*te,-p^alicl; 

UORD 

te— f ont ; 

MQRO 

te-Junkl; 

UORD 

t e-just; 

UORD 

te^olor; 

UORD 

tG-Junk2; 

UORD 

te— thickness; 

UORD 

te— txtlen; 

UORD 

te— tempi en; 

} TEDINFD; 

Figure  9-6  The  TEDINFO  Structure 

The  fidd  te-ptext  is  a pointer  to  the  storage  location  for  the  entered 
text  If  this  storage  location  alreacty  has  a string  in  it  this  string  is 
displayed  as  the  default  value  The  GEM  documentation  states  that  if 
the  first  character  in  the  string  is  the  ‘V’  symbol,  the  Add  is  con- 
sidered to  be  blank.  Any  remaining  characters  in  this  string  are 
merely  used  as  placeholders.  For  example,  the  string  V^Q^dq”  would 
show  seven  blank  spaces.  However,  this  feature  did  not  work  properly 
on  the  author's  qdem. 

The  te^tnqilt  fidd  is  used  for  those  object  types  that  allow  the  user 
to  enter  data.  These  objects  are  indicated  by  the  EDITABLE  object  flag 
setting.  This  TEDINFO  fidd  is  used  as  a pointer  to  a text  string 
template.  The  template  contains  the  format  of  text  Any  underscores 
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in  the  template  are  displayed  as  blanks  and  represent  the  editable 
characters  of  the  field.  For  example,  consider  this  template: 

Date: / / 

This  template  indicates  that  there  are  three  areas  for  data  to  be 
entered  for  a total  of  six  characters.  When  this  template  is  drawn  on 
the  screen,  the  user  is  only  able  to  change  the  characters  where  the 
underscores  are  located.  All  other  characters  are  shown  as  indicated. 

The  field  teL4tvalld  is  also  a pointer  to  a text  string.  This  string  is 
used  to  validate  any  entered  text.  The  characters  contained  in  the 
validation  strii^  evaluate  as  follows: 

the  digit  “9"  allows  onfy  the  digits  0 through  9 to  occur  at  this 
location. 

an  “A”  allows  only  spaces  and  upper-case  letters  to  be  entered. 

an  “a”  allows  upper-  and  lower-case  letters  and  the  space. 

an  “N”  allows  0-9,  A-Z,  and  the  space. 

an  “n”  allows  0-9,  A-Z,  a-z,  and  the  space. 

an  “F’  allows  all  valid  filename  characters  plus  “?”,  and 
This  type  of  validation  is  used  when  a filename  with  a drive  name 
and  wildcard  characters  should  be  entered. 

a “P"  allows  any  pathname  characters  plus  “?”,  and 

This  is  used  to  locate  files  in  other  directories. 

a “p”  allows  all  valid  pathname  characters,  plus  “\”  and  This 
allows  the  user  to  enter  a specific  file  name  but  not  the  wildcard 
characters. 

and  an  ‘X’  allows  any  character  to  be  entered. 

By  using  the  te_pvalid  field,  the  AES  routines  can  automatically 
perform  some  preliminaiy  data  verification.  For  example,  the  valida- 
tion string  for  the  date  entry  from  above  is  “999999”.  This  allows  any 
six-digit  entiy  to  be  placed  in  the  te_ptext  string.  From  this  string, 
you  can  verify  that  a valid  date  has  been  entered.  The  advantage  of 
using  the  validation  string  is  that  you  do  not  have  to  worry  about 
improper  characters  being  entered.  Note  that  the  nonunderscore 
characters  of  the  template  field  are  not  included  in  the  validation 
string. 

The  field  te-font  Indicates  the  font  to  be  used  for  drawing  the  text 
Ihe  value  3 means  the  ^tem  font  is  to  be  used  (the  font  used  for 
menus  and  dialog  boxes).  The  value  5 indicates  that  the  smaller  font 
is  to  be  used  (as  in  icons).  Field  te-junkl  (may  also  be  called 
te-resvdl)  is  a reserved  space.  The  te-just  field  is  a word  that 
Indicates  the  type  of  text  Justification  to  be  used  when  displaying  the 
string.  This  Justification  occurs  within  the  object  as  specified  ty  the 
ob-widOi  field  in  the  OBJEXH'  structure.  A value  of  0 is  left-justified 
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text.  1 is  right-justified,  and  2 is  centered.  These  values  have  defined 
constants  labeUed  TE_LEFT,  TELRIGHT,  and  TE_CNTR.  respectively. 

The  field  teucolor  indicates  the  color  and  the  pattern  of  objects  in 
boxes,  specifically  GJBOXTEXT  and  GJFBOXTEXT.  The  value  is  di- 
vided into  the  various  subfields  as  shown  in  the  low  word  of  Figure 
9-4.  The  te..jiuik2  (or  te_resvd2)  field  is  reserved.  The  field 
te-thickness  Indicates  the  thickness  in  pixels  of  the  border  of  a box. 
The  border  thickness  is  computed  in  the  same  way  as  in  the  high 
word  of  Figure  9-4.  Field  te^tsOen  is  the  length  of  the  string  pointed 
to  by  te-ptext  and  field  te  tmplen  is  the  length  of  the  string  pointed 
to  by  te-ptmplt 

The  AES  uses  the  TEDINFO  structure  with  the  object  types 
G_TEXT.  G-BOXTEXT.  G_FTEXT.  and  G_FBOXTEXT.  Object  type 
G_TEXT  is  simply  graphic  text,  which  is  a string  that  can  have  the 
various  attributes  supplied  in  the  TEDINFO  structure.  For  a GJTEXT 
object  the  ob-spec  field  of  the  OBJECT  structiue  points  to  a 
TEDINFO  structure.  The  field  te-ptest  of  the  TEDINFO  structure 
points  to  the  text  string  to  be  displayed.  The  G_BOXTEXT  object  Is 
a rectangle  containing  graphic  text  Again,  the  ob-spcc  field  points 
to  a TEDINFO  structure  that  contains  a pointer  in  the  te_ptext  field 
to  the  text  string.  The  TEDINFO  structure  also  contains  the  attributes 
for  the  box.  The  GJFTE2CT  object  is  formatted  graphic  text  Its 
ob-spec  field  points  to  a TEDINFO  structure.  The  TEDINFO  structure 
has  a pointer  to  a text  string  in  the  te-ptest  field  and  uses  the 
template  pointed  to  te-ptmplt  to  format  the  tect  The  G_FBOXTEXT 
object  Is  similar  to  the  G_FTEXT  object  with  the  addition  of  a 
rectangle  surroimdlng  the  text 

Ibe  ICONBLK  Structure 

Object  type  G_ICON  indicates  that  the  object  describes  an  icon.  An 
icon  is  a graphics  figure  used  to  represent  some  item  in  the  computer 
^tem  such  as  the  disk  drive  for  trash  can  on  the  desktop.  The 
ob..apec  field  for  a G_ICON  object  contains  a pointer  to  the  ICONBLK 
structure  (see  Figure  9-6.  The  ICONBLK  structure  holds  data  that 
defines  an  icon.  TTie  ib-pmask  field  is  a pointer  to  an  array  of  words 
representing  the  mask  bit  Image  of  the  icon.  This  is  similar  to  the 
meusking  concept  used  in  program  BOUNCE.  The  Ib_pdata  field  is  a 
pointer  to  an  array  of  words  representing  the  data  bit  image  of  the 
icon  itself  (like  the  ball  array  in  BOUNCE).  Fidd  ib.4>taat  is  a pointer 
to  the  Icon’s  text,  such  as  the  word  “TRASH"  under  the  trash  can. 
The  ib-char  fidd  is  a word  containing  the  character  to  be  drawn  on 
the  icon,  like  the  drive  letter  on  the  floppy  disk.  The  text  and  character 
Adds  may  be  empty  and  are  not  required.  The  fidd  ib-xchar  is  the  x 
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typadef  struct  lcDn_blocl<  { 

WORD  *ib_pmask; 

WORD  *lb_pdata; 

char  *lb-pt0xt; 

WORD  lb_char; 

WORD  ib«xchar; 

WORD  Ib^char; 

WORD  ib^icon; 

WORD  ib^icon; 

WORD  ib^icon; 

WORD  ib-hlcon; 

WORD  ib^text; 

WORD  ib^text; 

WORD  ib^text; 

WORD  ibJitext; 

} ICONBLK; 

Figure  9-6  Hie  ICONBLK  Structure 

coordinate  in  pixels  of  the  character,  and  field  ib-ychar  is  the  y 
coordinate  of  the  character.  Again,  the  coordinates  are  relative  to  the 
upper  left  comer  of  the  icon.  Tlie  ib-zicon  and  ib_yicon  fields  are 
the  X and  y source  coordinates  of  the  icon,  used  as  in  the  raster  copy 
functions  of  the  VDI.  Field  Ib-wicon  contains  the  width  of  the  Icon. 
As  with  the  rasters,  this  width  value  must  be  divisible  by  16  (an 
integral  word  width).  The  Ib-hicon  field  contains  the  height  of  the 
icon.  The  tb-ztest  and  fl>-ytezt  fields  are  the  x and  y coordinates  of 
the  Icons’s  text  The  Ib-wtezt  and  fl>_htext  are  the  width  and  height 
of  a rectangle  for  the  icon  text  The  text  is  centered  within  this 
rectangle.  All  size  and  position  valu^  are  measured  in  pixds. 

The  BI1BLK  Structure 

Object  type  G-IMAGE  is  a bit  image  object  just  like  a raster.  The 
ob-spec  field  for  a G-IMAGE  object  points  to  a BITBLK  stmcture  as 
shown  in  Figure  9-7.  The  bL.pdata  field  of  this  stmcture  points  to  an 
array  of  words  containing  the  bit  image  (that  Is.  raster).  Field  bi_wb 
is  the  width  of  the  bL^>data  array  in  bytes.  Because  the  bi.pdata 
array  is  made  of  words,  the  width  must  be  an  even-numbered  value 
because  there  are  two  bytes  per  word.  The  bi-hl  field  is  a word 
containing  the  height  of  the  bit  block  in  plxela  The  bL.z  is  the  source 
X coordinate  relative  to  the  bL^xlata  array,  and  bi.y  is  the  y source 
coordinate  relative  to  that  array.  These  values  have  the  same  use  as 
the  source  coordinates  used  in  the  raster  copy  functions  of  the  VDI. 
The  field  bi-color  is  a word  containing  the  color  that  the  AES  uses 
to  display  the  image.  The  color  index  values  are  shown  in  Table  9-4. 
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typedsf  struct  bit-block  { 


MORD 

*bi_pdata; 

MORD 

bi^b; 

tlORD 

biJnl; 

tlORD 

bi-x; 

tlORD 

bi_y; 

loJDRD 
} BITBLK; 

bi-xolor; 

Figure  9-7  Ibe  BTIBUE  Stnetnre 


Td>le9-4:  Olject  Color 
Index  Values 


Constant  Name 

Value 

WHITE 

0 

BLACK 

1 

RED 

2 

GREEN 

3 

BLUE 

4 

CYAN 

5 

YELLOW 

6 

MAGENTA 

7 

LWHITE 

8 

LBLACK 

9 

LRED 

10 

LGREEN 

11 

LBLUE 

12 

LCYAN 

13 

LYELLOW 

14 

LMAGENTA 

15 

Hie  APPLBLK  and  RARMBLK  Structures 

Object  type  G-PROGDEF  is  a programmer-defined  object.  When  a 
program  tells  the  AE^  to  draw  an  object  or  object  tree,  the  AES 
traverses  through  the  tree  and  draws  each  object  and  Its  children  (if 
thQT  are  not  flagged  as  being  hidden).  For  each  object  type,  the  AES 
has  a routine  to  draw  that  particular  object  on  the  screen.  For 
example,  object  type  G JBOXTE3CT  has  a routine  that  draws  a box  and 
then  draws  text  within  the  box.  Object  type  G-PROGDEF  tells  the 
AES  that  this  object  is  not  one  of  the  standard  object  types  and 
requires  a special  handling  routine.  The  location  of  this  custom 
routine  is  provided  in  the  ab-code  field  of  the  APPLBLiC  structure  (see 
Figure  9-8).  This  field  contains  the  pointer  to  the  custom  routine.  The 
other  field  in  the  APPLBLK  structure,  called  ab-parm,  is  a value  of 
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typedef  struct  appl_bll<  { 

int  (*ab_code)  ( ) ; 

long  ab-parm; 

) flPPLBLK; 

Fignie  9-8  Hie  AIVLBLK  Stnxctnre 

type  long.  This  is  used  as  a four-byte  parameter  to  the  custom 
routine.  A program  can  divide  these  four  bytes  in  any  combination: 
four  cheiracters  (one  b3de  each),  two  integers  (two  bytes  each),  one 
integer  and  two  characters,  a long  integer  (four  l^es),  or  a pointer 
(four  bytes). 

When  the  AES  draws  or  changes  an  object,  it  needs  much  more 
information  than  can  be  supplied  in  just  four  b}rtes.  Tliis  information 
includes  the  location  of  the  object  tree,  the  index  of  the  object  being 
drawn  or  changed,  the  location  of  the  object  and  so  on.  When  the 
AES  encounters  a custom  object  it  calls  the  routine  specified  by  the 
ab-code  field  and  provides  this  routine  (as  a parameter)  with  the 
additional  information  in  a PARMBLK  structure  (see  Figure  9-9).  In 
this  structure,  the  pb-tree  field  is  a pointer  to  the  object  tree  that 
contains  the  object  to  be  operated  upon.  The  pbL^b}  field  contains 
the  index  of  that  object  within  the  tree.  Since  object  trees  are  stored 
as  arra}TS,  the  index  is  the  element  number  of  the  object.  The 
pb_prev8tate  field  is  the  previous  state  of  the  object  to  be  changed, 
and  the  pb_cuxrstate  field  is  the  new  state  of  the  object  When 
pb-pievstate  and  pb_cuxrstate  are  the  same,  the  application  draws 
the  object  and  does  not  change  it  Fields  pb_x  and  pb_y  are  the  x and 
y coordinates  of  the  upper  left  comer  of  a rectangle  defining  the 
location  of  the  object  Fields  pb-w  and  pb-h  are  the  width  and  height 
of  the  rectangle.  The  next  four  fields,  pb-zc,  pb_yc,  pb-wc,  and  pb_hc, 
determine  the  location  and  size  of  the  clipping  rectan^e.  llie  x and 
y coordinates  are  the  upper  left  comer  of  the  rectangle  and  are  given 
by  pb_zc  emd  pb_3rc.  The  width  and  height  are  given  by  pb_wc  and 


typedef  struct  parm_blk  { 

OBJECT  *pb_tree; 

UORD  pb-jobJ ; 

UORD  pb_preustate; 

UORD  pb^urrstate; 

UORD  pb_x,  pb_y,  pb-u,  pb_h; 

UORD  pb_xc,  pb_yc,  pb_uic,  pb_hc; 

long  pb_parm; 

} PflRMBLK; 

Flguie  9-9  Tbe  PARSIBLK  Stractiire 
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pb-hc.  The  dipping  rectangle  is  used  here  just  as  in  the  VDI.  Any- 
thing outside  of  the  dipping  rectangle  is  not  drawn.  The  pb_parm 
fldd  is  set  to  the  same  value  as  the  ab-parm  fldd  in  the  APPLBLK 
structure.  All  coordinate  values  for  this  structure  refer  to  the  physical 
screen.  In  other  words,  the  x and  y coordinates  for  the  object  and 
the  dipping  rectangle  are  the  x and  y coordinates  on  the  screen.  They 
are  not  relative  to  the  parent  object 
The  information  about  objects  and  their  related  structures  is  a very 
powerful  tool  in  the  program;  this  is  done  by  defining  an  object  tree  for 
a dialog  box,  menu,  icon,  or  other  object  you  want  displayed  on  the 
screen.  Pass  this  tree  to  the  appropriate  AES  routine,  and  it  empears 
on  the  screen.  Don’t  be  overwhelmed  by  the  complexity  of  creating  an 
image  on  the  screen,  even  an  image  as  simple  as  a dialog  box.  The  AES 
contains  many  routines  that  assist  you  in  handling  object  tree 
management  like  adding,  ddeting,  reordering,  and  changing  objects. 
Other  AES  routines  perform  the  drawing  of  objects,  data  entry,  data 
verification,  as  well  as  the  user  Interaction  Involved  with  the  selection 
of  boxes  and  icons. 


The  Resource  Constmction  Program 


The  use  of  objects  in  a GEM  application  is  a very  basic  requirement 
However,  even  with  assistance  from  the  AEiS  routines,  the  creation  of 
object  trees  is  a quite  cumbersome  task.  To  relieve  your  program  of 
the  tedium  of  creating  the  data  and  making  sure  that  is  correct  there 
is  a program  provided  that  creates  the  resource  file  to  be  used  by  the 
program.  The  Megamax  compiler  comes  with  a program  called 
MMRCP,  which  allows  you  to  create  a resource  file.  The  Atari 
developer’s  kit  also  comes  with  a program  called  RCS  that  performs 
the  same  task.  The  two  programs  produce  a resource  file.  Since  the 
objects  have  a predefined  format  you  may  use  either  program  to 
create  the  same  resource  file. 

At  the  time  of  this  writing,  the  version  of  the  Megamax  MMRCP 
program  had  a problem  when  writing  out  the  resource  file.  The 
discussion  of  the  resource  program  therefore  concerns  the  Atari/Dlgltal 
Research  RCS  program.  The  concepts  discussed  here  are  the  same  for 
both  programs.  However,  the  operation  of  each  program  is  slightly 
different 

To  do  the  remaining  programs  in  this  book,  you  need  a resource 
editor  program  or  some  method  of  creating  the  resource  files  to  be 
used  by  the  programs.  Therefore,  at  this  point  a brief  tutorial  for  the 
RCS  resource  construction  program  is  provided. 

First  read  through  the  manual  for  the  resource  editing  program 
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you  are  using.  Familiarize  yourself  with  its  features  and  general 
operation.  Then  load  this  program  on  your  Atari  ^tem,  and  execute 
it.  For  the  RCS  program,  you  see  a menu  bar,  a window  caUed 
“RESOURCE  PARTBOX,”  a window  called  “RESOURCE  CONSTRUC- 
TION SET,"  a clipboard,  and  a trash  can.  The  RESOURCE  PARTBOX 
window  contains  icons  for  the  various  types  of  objects  trees  that  you 
can  create.  These  are  a menu,  a dialog  box,  an  alert  box,  a free  tree, 
and  a tree  of  unknown  type.  A free  tree  is  simply  a tree  that  contains 
a set  of  objects.  A tree  of  this  type  is  usually  just  to  format  a display 
screen.  The  unknown  tree  type  is  used  when  the  resource  editor 
program  is  changing  an  existing  resource  file  and  does  not  know 
what  type  of  tree  to  use.  For  example,  if  you  read  in  the  resource  file 
for  the  resource  editor  (file  RCSJ%^  for  the  RCS  program),  you  see 
a bunch  of  trees  of  unknown  type.  If  you  are  not  using  the  RCS 
program,  your  screen  should  have  a menu  bar,  some  portion  of  the 
screen  containing  the  tree  type  icons,  and  a portion  of  the  screen  that 
is  used  for  editing  the  resource  file. 

You  are  now  going  to  create  a dialog  box.  To  begin,  use  the  File 
menu  to  open  a new  file.  For  the  RCS  program,  selecting  the  New 
option  causes  the  workspace  to  be  cleared.  Any  program  may  contain 
any  number  of  object  trees  (memory  space  permitting).  For  example, 
the  RCS  program  has  a tree  for  the  menu  bar  and  many  dialog  boxes 
such  as  a dialog  box  for  the  Program  Information  option  In  the  Desk 
menu,  and  a dialog  box  to  name  an  object  Each  of  these  trees  is  given 
a root  To  “plant”  (create)  a tree,  drag  the  appropriate  tree  icon  from 
the  part  box  to  the  work  area.  For  the  dialog  box  example  used  here, 
drag  a dialog  tree  to  the  work  area.  At  this  point  the  RCS  program 
displays  its  own  dialog  box  requesting  the  name  of  the  tree  with  a 
default  name  of  TREEl..<Change  this  name  to  EN7RYBOX.  If  30ur 
resource  editor  did  not  request  a name,  select  this  tree  by  clicking  on 
it  once.  Then  use  the  Name  option  in  the  menu  (or  something 
equivalent)  to  set  the  name  of  this  dialog  box  object  tree. 

Now  that  you  have  set  the  root  of  the  tree,  3rou  need  to  define  what 
the  contents  of  the  dialog  box  will  look  like.  This  is  done  by  placing 
objects  into  the  dialog  box.  Double-dlck  the  ENTRYBOX  icon.  This 
opens  a window  for  the  dialog  box  and  sets  the  parts  box  to  contain 
the  objects  that  you  may  want  to  use.  The  contents  of  the  parts  box 
vary  from  program  to  program.  In  general,  it  contains  such  objects  as 
a button,  a string,  formatted  text  editable  fields,  and  boxed  text  Just 
as  in  planting  a tree,  you  place  objects  in  the  dialog  box  hy  dragging 
them  from  the  parts  box  to  the  work  area.  The  dialog  box  you  are  now 
creating  is  a sample  survey  form  that  demonstrates  how  to  use 
editable  fields,  templates,  data  validation,  buttons,  radio  buttons,  and 
default  &dt  conditions  (see  Figure  9-10). 
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PERSONRL  DATA  SHEET 


Last  Nans: 
First  Hans: 


Vearly  Incone 
Under  $M,999 
$15,000  - $24,999 
$25,000  - $49,999 
$50,000  and  over 


Chaek  One 


Date  of  Birth: / / — 

* of  Years  at 

Current  Address: 


Hobbies 

Skiing 

Tennis 

Itusic 

Suinning 


Cheek  Al I 
That  Apply 


Quit 


Pigine  9>10  ramCTBGit  Dialog  Boa 


Clear  Fern 


The  titie  of  the  dialog  box,  “PERSONAL  DATA  SHEET.”  is  just  a 
string  object  To  create  the  title,  take  a string  object  from  the  dialog 
part  box  and  place  It  at  the  location  of  the  dialog  box  title.  You  now 
have  a tect  string  that  says  “STRING”  at  this  position.  Double-dick 
this  object  and  the  resource  editor  program  opens  up  another  of  its 
own  dialog  boxes.  This  dialog  box  aUows  you  to  set  the  various  object 
flags  and  states  for  this  object  At  the  bottom  of  the  box  is  a line  that 
says: 

TEXT:  STRING 

Whatever  you  enter  in  this  field  becomes  the  text  that  is  displayed  for 
this  object  Press  the  Escape  kqr  to  dear  the  text  fldd  and  enter  the 
words  “PERSONAL  DATA  SHEET.”  CUck  the  OK  button.  The  dialog 
box  disappears  and  the  new  text  of  the  title  is  shown  on  the  box  you 
are  creating. 

To  create  the  editable  text  Adds  for  the  first  and  last  name  data. 

use  the  unboxed  edit  object  This  is  the  object  that  says  “EDIT: ” 

Drag  this  object  onto  your  dialog  box.  and  place  it  at  the  location  of 
the  last  name  entry  fidd  (refer  to  Figure  9-10).  Double-dlck  this  new 
object  and  another  dialog  box  appears.  This  box  has  object  flag  and 
state  sdectlons.  background  color  and  intensity,  border  color  and  size, 
character  color,  font  justification,  writing  mode  (called  Rule  in  the 
RCS).  and  text  fields.  Because  this  particular  object  is  not  a boxed 
object  the  backgroimd  and  border  sdectlons  have  no  effect  on  how 
this  object  is  displ^^.  These  options  are  induded  here  because  this 
dialog  box  is  also  used  for  the  boxed  EDIT: object 

Note  that  the  object  flag  button  labded  “EiDITABLE”  Is  sdected 
(shown  in  reverse  colors).  This  is  the  default  flag  setting  for  the 
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EDIT: object  and  indicates  that  this  object  is  editable.  If  this 

flag  is  not  set  when  your  program  activates  this  dialog  box,  the  AES 
does  not  let  the  user  edit  this  field.  For  the  dialog  box  }rou  are 
creating,  change  the  PTMPLT  line  at  the  bottom  to  show: 

Last  Name:^ — 

Use  the  up,  down,  left  and  right  arrows  on  the  k^oard  to  move  the 
text  cursor.  When  used  in  the  resource  editor  program,  the  tilde 
character  (~)  indicates  an  underscore.  This  is  done  because  the 
underscore  is  already  used  to  show  what  portions  of  the  field  may  be 
edited.  If  you  enter  ^e  underscore,  there  is  no  way  of  knowing  vtdiat 
portion  of  the  field  is  your  entry  and  what  portion  is  displayed  by  the 
program. 

The  PVALID  line  is  the  validation  text  This  line  must  match  the 
format  of  PTMPLT  line  in  that  you  must  place  the  validation  charac- 
ters at  the  exact  position  of  the  entry.  In  other  words,  wherever  you 
do  not  want  data  to  be  entered,  place  a tilde.  Wherever  you  want  data 
to  be  entered,  place  the  ^propriate  data  validation  character  (see  the 
TEDINFO  structure  above).  For  this  dialog  box,  place  tildes  under  the 
“Last  Name:"  portion  of  the  PTMPLT  line.  Then  put  a capital  X under 
each  tilde  in  the  PTMPLT  line.  The  format  of  these  fidds  may  vary 
slight^  among  resource  editor  programs;  however,  the  general  layout 
remains  the  same. 

The  PTEXT  field  is  the  default  text  to  be  displayed  when  the 
program  is  run.  When  the  AE^  displays  this  dialog  box,  the  string 
shown  on  this  line  appears  as  the  current  value  of  the  entered  date. 
The  PTEXT  field  also  determines  the  maximum  number  of  characters 
the  user  may  enter.  This  field  is  formatted  with  tildes  used  for  places 
where  no  text  is  entered  and  underscores  (_)  where  text  will  be 
entered.  When  the  AES  draws  this  dialog  box,  it  draws  the  PTMPLT 
field  replacing  the  tildes  with  the  text  from  the  PTEXT  field.  In  this 
example  dialog  box,  you  need  1 1 tildes  followed  l^  15  underscores  to 
match  the  format  of  the  PTMPLT  field.  Enter  these  values  for  the 
PTMPLT,  PVALID,  and  PTEXT  flelda 

PTMPLT>Last  Name: — 

PVALID> XXXXXXXXXXXXXXXX 

PTEXT> 

Click  OK  and  when  the  object’s  dialog  box  disappears,  you  see: 

Last  Name- 

which  is  what  is  shown  when  the  AE^  draws  this  object 

Logically,  you  might  think  that  the  PTMPLT  field  should  control  the 
format  of  the  object,  the  PVALID  field  should  have  only  the  valida- 
tion portion  of  the  string,  and  the  PTEXT  field  should  have  onty 
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the  default  text  In  the  RCS  program,  this  Is  not  the  case.  The  PVALID 
and  PTEXT  fields  must  match  the  format  of  the  PTBflPLT  field.  Other 
resource  editor  programs  may  have  different  requirements. 

Take  another  edit  held  and  create  a first  name  entry  field  in  the 
same  manner  you  created  the  l^t  name  entry  field.  The  first  name 
entry  field  has  the  following  values: 

PTMPLT>First  Name: 

PVALID> 'XXXXXXXXXXXXXXXX 

PTEXT> 

For  the  date  of  birth  entry,  the  values  are  these: 

PTMPLT>Date  of  Birth: — / — / — 

FVALID> 99-99-99 

PTEXT> .- .- 

Notice  that  tildes  are  placeholders  for  noneditable  characters  and  that 
the  validation  string  uses  the  character  “9”  to  allow  only  numeric 
values. 

The  text  of  Years  at"  is  a STRING  object  like  the  box  title.  Create 
this  string  in  the  same  maimer  as  before,  then  make  the  "Current 
Address"  entry  field  with  these  values: 

FIMPLT>Current  Address:— 

PVALID> 99 

PTEJCT> 

This  fldd  allows  a two-digit  value  to  be  entered. 

Hie  remaining  objects  in  this  dialog  box  are  strings  and  buttons. 
The  yearty  income  items  are  all  STRING  objects  as  are  the  hobby 
items.  Create  the  STEtING  objects  for  the  yearly  Income  selections  and 
the  hobby  selections  Including  the  headings  ‘Yearly  Income"  and 
“Hobbies." 

The  small  objects  that  say  “Check  One"  and  “Check  All  That  .^pfy" 
are  TEXT,  not  STRING,  objects.  A STRING  object  allows  you  only  to 
enter  a string  and  set  some  of  the  object  flags  and  states.  A TEXT 
object,  in  addition  to  setting  the  text  flags,  and  states,  also  allows  you 
to  set  the  font  size,  text  justification,  colors,  and  writing  mode. 
Because  small  lettering  is  used  in  the  ENTRYBOX  dialog  box,  the 
TEXT  object  is  required.  Three  TEXT  objects  are  needed:  one  for 
“Check  One,"  one  for  “Check  All."  and  one  for  “That  i^ply."  Because 
“Check  All  That  >^pfy”  is  split  across  two  lines,  two  TEXT  objects  are 
required.  Drag  three  TEXT  objects  from  the  parts  box  to  the  work  area 
and  place  them  at  the  appropriate  locations  Double-dick  the  TEXT 
object  for  the  “Check  One"  object  and  a dialog  box  is  displayed.  This 
is  the  same  dialog  box  used  for  the  editable  text  fldds.  With  a TEXT 
object,  however,  the  PTMPLT  and  PVALID  Adds  have  no  effect  Onty 
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the  PTEXT  field  Is  used,  and  It  should  be  set  to  read  “Check  One." 
Next  select  the  small  font  eind  dick  OK.  Repeat  this  procedure  for  the 
other  two  TEXT  objects,  “Check  M"  and  “That  Appfy.” 

By  now  you  may  have  noticed  that  whenever  you  place  an  object  in 
your  dialog  box.  It  appears  to  line  up  on  an  Invisible  grid.  When  you 
are  editing  a dialog  box,  all  objects  contained  in  It  are  character- 
aligned.  This  means  that  the  dialog  box  is  divided  into  character  cells. 
The  start  of  an  object  must  lie  in  one  of  these  cells.  You  cannot  place 
an  object  half-way  between  cells,  and  the  length  of  an  object  must  be 
a whole  number  of  cells.  This  relieves  you  of  having  to  align  the  text 
by  hand.  If  you  want  more  control  over  where  you  can  place  an  object 
use  the  free  tree. 

At  this  point  you  now  have  a form  that  has  all  the  text  in  it  You 
now  need  to  create  the  four  boxes  for  yearly  income,  the  four  boxes 
for  hobbies,  and  the  three  buttons  at  the  bottom  of  the  form,  llie 
yeaify  income  sdection  uses  radio  buttons  because  onty  one  Income 
level  at  a time  is  allowed.  As  mentioned  earlier,  radio  buttons  require 
a common  parent  In  other  words,  all  radio  buttons  in  a set  must  be 
children  of  the  same  parent  To  create  a common  parent  drag  the 
single  outlined  box  from  the  parts  box  to  the  area  under  the  “Check 
One”  object  and  next  to  the  “Under  $14,999”  object  You  now  have  a 
horizontal  box  where  you  want  a vertical  box.’^Therefore,  you  need  to 
resize  this  object  To  do  this,  select  the  box  object  by  clicking  on  it 
once.  This  causes  the  object  to  be  shown  in  reverse  colors.  Now  place 
the  tip  of  the  mouse  arrow  cursor  at  the  bottom  right  comer.  When 
you  press  the  mouse  button,  the  arrow  cursor  changes  to  the  finger 
cursor.  This  may  take  a few  attempts  to  hit  the  exact  spot  on  the 
object  for  sizing.  With  the  finger  cursor,  you  can  resize  the  object  Just 
as  you  would  resize  a window.  Releasing  the  mouse  button  sets  the 
new  object  size.  You  can  move  an  object  by  placing  the  arrow  cursor 
at  the  center  of  the  object  and  pressing  the  mouse  button.  The  arrow 
cursor  changes  to  the  open  hand  cursor,  and  you  can  drag  the  object 
to  its  new  location.  Resize  the  common  parent  box  so  that  it  is  about 
three  characters  wide  and  four  lines  tall  under  the  “Check  One”  object 
(see  the  shaded  area  Figiire  9-10).  Move  the  box  if  required. 

You  now  have  the  box  to  be  used  as  the  common  parent  You  now 
need  to  add  the  four  children.  An  object  is  considered  the  child  of 
another  object  if  the  parent  object  completely  encloses  the  child.  For 
example,  all  the  objects  you  have  placed  in  the  dialog  box  so  far  are 
children  of  the  dialog  box  because  the  dialog  box  contedns  these 
objects.  To  create  a small  box,  take  a sln^e  outlined  box  from  the 
parts  box  and  place  it  in  an  empty  area  of  the  dialog  box  such  as  the 
upper  left  comer.  Resize  the  new  box  so  that  it  is  one  line  high  and 
one  character  wide.  Drag  this  box  so  that  it  is  under  the  “Check  One" 
object  on  the  same  line  as  the  “Under  $14,999”  object  and  fully 
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enclosed  by  the  parent  box  you  just  created.  If  3^u  are  using  the  RCS 
program,  you  receive  an  alert  box  saying  that  this  move  rearranges 
the  tree.  What  is  happening  is  that  you  are  taking  a child  of  the  dialog 
box  (because  it  was  contained  only  by  the  dialog  box)  and  making  it 
a child  of  the  parent  box.  This  changes  how  the  tree  looks.  To  verify 
that  you  want  to  complete  this  action,  the  RCS  program  warns  you 
of  the  situation  and  allows  you  to  cancel  the  move.  In  creating 
ENTRYBOX.  you  want  to  change  the  order  of  the  tree.  Create  three 
more  boxes  for  the  remaining  three  income  levels. 

In  the  final  form  of  the  dialog  box.  you  do  not  want  the  parent  box 
to  be  visible.  Therefore,  double-click  this  box  and  change  the  border 
to  be  invisible  (that  is.  no  border).  Click  OK.  and  when  ENTRYBOX  is 
redisplayed,  the  parent  box  will  be  invisible. 

You  now  have  four  small  boxes  surrovmded  by  an  invisible  parent 
box.  These  four  boxes  must  be  turned  into  radio  buttons.  Double-dick 
the  top  box.  This  causes  a dialog  box  to  be  displayed.  This  dialog  box 
allows  you  to  set  the  flags,  states,  and  text  of  a box.  Click  the 
SELEXiTABLE  flag.  This  turns  the  box  into  a button  the  user  can 
select  with  the  mouse.  Also  dick  the  RADIO  BUTN  flag  to  make  the 
button  into  a radio  button.  The  TEXT  field  remains  blank  because 
there  is  no  text  for  this  button.  Click  OK  and  that’s  all  there  is  to 
making  a radio  button.  Repeat  this  procedure  for  the  other  three 
boxes.  The  radio  buttons  are  now  ready. 

The  hobby  selection  also  requires  four  selection  or  check  boxes. 
These  are  not  radio  buttons  because  a person  may  have  more  than 
one  hobby.  Create  four  small  boxes  and  place  them  in  a column.  For 
each  box.  double-dick  it  and  choose  the  SELEXnABLE  flag  only. 
These  boxes  are  now  buttons.  Altemativdy.  instead  of  using  the  single 
outlined  boxes,  you  can  use  the  BUTTON  object  that  already  has  its 
SELEXITABLE  flag  set 

The  top  portion  of  the  form  is  now  completely  set  The  next  step  is 
to  set  the  three  buttons  at  the  bottom  of  the  form.  Take  three 
BUTTON  objects  from  the  parts  box.  and  put  one  in  place  for  each 
button.  At  this  point  jrau  are  probably  running  out  of  room  on  the 
screen.  Click  the  full  box  (at  the  right  end  of  the  title  bar)  to  change 
the  size  of  the  window.  You  can  now  resize  the  dialog  box  itsdf  and 
move  the  buttons  to  their  appropriate  locations. 

The  OK  button  is  an  exit  button.  If  the  user  sdects  this  button,  the 
AES  stops  processing  the  dialog  box  and  returns  control  to  the 
application  program.  EX/eiy  dialog  box  must  have  some  form  of  exit 
object;  otherwise,  the  user  can  never  get  back  to  the  program.  The  OK 
button  is  also  the  default  exit  sdection  so  that  if  the  user  presses  the 
REHURN  key.  the  OK  button  is  automatically  sdected.  Double-click 
the  button  that  becomes  the  OK  button.  Given  the  above  parameters, 
the  SELEXITABLE.  DEFAULT,  and  EXIT  flags  should  be  set  in  the 
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dialog  box  (SELECTABLE  is  already  set  for  a BUTTON  object).  The 
TEXT  field  should  be  set  to  read  “OK.”  Upon  return  to  the  ENTRYBOX 
dialog  box  that  you  are  creating,  you  will  notice  that  the  OK  button 
has  a thicker  outline  than  the  other  buttons  on  the  form.  The  thick 
border  indicates  that  the  OK  button  is  the  default  exit  value. 

Double-dick  the  button  that  is  used  to  quit  Change  its  text  to  read 
“QUIT"  and  select  the  EXIT  flag  (the  SELECTABLE  fl^  is  already  set). 
When  ENTRYBOX  is  redisplayed,  this  button  says  QUIT  and  its  border 
has  a medium  thickness.  A button  with  medium  thickness  indicates 
an  exit  button  that  is  not  the  default 

Finally,  double-click  the  last  button.  Choose  the  EXIT  flag,  and 
change  its  text  to  read  “Clear  Form.”  This  button  is  used  if  the  person 
wishes  to  elear  the  form  without  further  processing. 

You  have  now  created  all  the  objects  used  by  the  ENTRYBOX  dialog 
box.  You  could  save  this  in  a resource  file  and  use  the  resource  file 
in  a program.  However,  there  is  one  smaU  problem.  Memy  AE^  func- 
tions require  that  you  know  the  index  number  of  the  objects  you  need 
to  access.  Depen^ng  upon  the  order  in  which  you  created  the 
resource  file,  these  index  numbers  vary.  Therefore,  if  you  edit  the 
resource  file  and  add  or  delete  objects,  the  index  numbers  change. 
How  do  you  know  what  index  numbers  to  use? 

Fortunately,  the  RCS  program  and  the  MMRCP  program  allow  you 
to  name  the  objects.  For  example,  ENTRYBOX  is  the  neune  of  the  tree 
used  for  the  dialog  box.  The  name  of  the  object  is  then  used  as  a 
defined  constant  within  your  program.  When  you  save  the  resource 
file,  the  resource  editor  program  writes  the  resource  file  and  a C 
header  file  containing  the  names  of  the  objects  (objects  not  named 
are  not  included  in  the  header  file).  If  you  save  ENTRYBOX  in  its 
current  state,  3rou  would  get  a resource  file  and  a header  file  contain- 
ing the  statement: 

^define  ENTRYBOX  0 

The  name  ENTRYBOX  is  associated  with  the  root  of  the  dialog  box 
(the  box  itself)  and  its  index  in  the  tree  is  element  0.  By  using  the 
defined  constant  names  and  ineluding  the  header  file  in  your  C 
program,  you  need  not  concern  yourself  with  the  actual  index  values 
when  writing  the  program.  Also,  if  )Ou  want  to  add  more  objects, 
simply  do  so  and  then  recompile  }our  program.  The  header  file  will 
contain  the  new  index  values  for  the  constant  names  used  by  your 
program. 

To  name  an  object  click  it  once  to  select  it  Then  choose  the  Name 
selection  from  the  Options  menu  (or  whatever  is  £q>proprlate  for  your 
resource  editor  program).  For  example,  select  the  last  name  entry  field 
and  choose  the  Name  selection.  You  get  a dialog  box  that  allows  you 
to  enter  the  name  of  the  object  emd  change  the  object  type.  Gener^y, 


Application  Elnvlronment  Services:  The  AES  239 


it  is  not  a good  idea  to  change  the  object  lype  unless  you  really  must 
The  Name  held  is  blank.  Enter  LNAME.  Object  names  should  be  in 
ce^ital  letters  (which  is  a good  idea  since  these  names  will  be  used 
for  the  defined  constant  names)  and  are  limited  to  eight  characters. 
The  RCS  program  does  not  allow  the  underscore  to  be  used  in  an 
object  name;  actual^,  entering  an  underscore  caused  the  program  to 
exit  abnonnally.  This  is  probabfy  a bug  in  the  program.  After  entering 
the  object  name,  click  the  OK  button.  That  is  all  there  is  to  naming 
an  object  Now  when  the  header  file  is  written,  there  is  also  a state- 
ment defining  the  constant  name  LNAME.  Repeat  this  naming 
procedure  for  the  other  objects  in  the  dialog  box  as  shown  in  Table 
9-5.  Note  that  not  all  the  objects  are  named.  Only  those  objects  that 
are  accessed  by  a program  are  named.  Tlie  first  name  field  should  be 
called  FNAME.  Date  of  Birth  should  be  called  Birthday.  Current  ad- 
dress should  be  called  HOME^GE.  Select  the  box  associated  with  an 
income  of  less  than  $14,999.  Name  it  INCl.  Name  the  next,  in  order, 
INC2.  INC3,  and  1NC4.  For  the  hobbies,  name  the  box  next  to  “skiing” 
as  HOBl.  The  others  are  HOB2,  HOBS,  and  HOB4.  All  the  data  items 
are  now  named.  Finally,  name  the  “OK”  button  OK  Name  the  Quit 
button  QUIT  and  the  Clear  Form  button  CLEIAR 


Table  9-5:  Ol^ect  Name  for  the 
ENTRTBOX  I^og  Box 


Object  Field  on  Form 

Object  Name 

Last  Name 

LNAME 

First  Name 

FNAME 

Date  of  Birth 

BIRTHDAY 

Current  Address 

HOMEAGE 

Radio  button  for 

Under  $14,999 

mci 

$15,000-$24.999 

INC2 

$25,000-$49,999 

INC3 

$50,000  and  over 

INC4 

Selection  button  for 

Skiing 

HOBl 

Tennis 

HOB2 

Music 

HOBS 

Swimming 

HOB4 

OK  button 

OK 

QUIT  button 

QUIT 

Clear  Form  button 

CLEAR 

After  naming  the  objects,  press  the  full  box  again  to  restore  the  win- 
dow to  its  normal  size.  Then  dose  the  window  for  the  ENTRYBOX 
dialog  box.  The  program  returns  to  the  main  window,  which  shows 
the  dialog  box  icon  for  ENTRYBOX. 
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In  the  File  menu,  use  the  Save  or  Save  As...  option  to  save  this 
resource  file.  Use  the  filename  FORM.RSC.  Elxit  from  the  resource 
editor  program.  When  you  return  to  the  desktop,  you  see  the  file 
FORM.RSC  in  the  dlrectoiy,  and  two  other  new  files:  PORM.DEF  and 
FORM.H.  PORM.DEF  is  a definition  file  that  is  used  the  resource 
editor  program.  It  contains  the  names  and  basic  layout  of  the 
resource  file.  If  a .DEF  file  does  not  exist  for  a .RSC  file,  then  when 
you  tiy  to  edit  the  resource  file,  you  get  trees  with  the  unknown  tree 
type  because  the  resource  editor  program  does  not  know  the  layout 
of  the  file.  File  FORMJi  is  the  header  file  to  be  Included  in  your 
program.  Double-click  this  file.  GEM  gives  you  a dialog  box  that  says 
you  can  only  print  or  display  this  document  Select  the  Show  option 
to  display  the  contents  of  the  header  file  on  the  screen.  You  see  a set 
of  *d^ne  statements  that  list  all  the  object  names  you  entered.  The 
number  following  the  ^define  name  is  the  index  for  that  object  in  the 
tree. 


The  AES  Review 


With  this  introduction  to  the  AES,  you  have  learned  all  the  basic 
concepts  associated  with  writing  programs  for  a GEM  s^plicatlon. 
Because  of  the  amount  of  Information  presented  here,  we  are  includ- 
ing a quick  review  of  the  more  complex  and  necessary  concepts. 

You  should  intuitively  understand  how  to  use  menus  and  windows. 
These  are  basic  elements  to  using  the  Atari  computer,  so  it  is  as- 
sumed that  you  have  a working  knowledge  of  these  units.  The  first 
important  concept  to  understand  is  the  object  An  object  is  simpty  a 
graphics  unit  that  the  AE2S  can  draw  and  posslbfy  edit  Objects  are 
logical^  group>ed  into  units  called  trees.  A tree  describes  a particular 
AES  aspect  such  eus  a menu  bar,  a dialog  box,  or  an  alert  box.  A tree 
has  a root  object  that  generalfy  describes  the  type  of  tree.  Each  object 
in  a tree  has  one  parent  (except  the  root  which  has  no  parents)  and 
any  number  of  children.  The  AES  Implements  the  tree  data  structure 
as  an  array.  To  access  a particular  object  in  an  array,  you  must  know 
the  index  number  of  the  object  in  the  tree. 

Information  ed>out  a particular  object  is  held  in  an  OBJEX)T  struc- 
ture. This  structure  contains  data  such  as  indices  to  the  object’s 
sibling,  first  child,  last  child,  object  type,  state,  flags,  relative  location 
on  the  screen,  and  a specification  field.  If  more  Information  is  re- 
quired by  the  particular  object  type,  an  additional  structure  is  used. 
Of  these  additional  structures,  the  one  used  most  is  the  TEDINFO 
structure.  This  structure  is  used  with  object  that  have  editable  text 

To  relieve  the  program  from  the  tedliun  of  having  to  create  object 
trees,  a GEM  development  ^tem  usually  comes  with  a resource  file 
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editor  program.  This  program  allows  the  programmer  to  create  and 
edit  resource  flies  which  hold  the  object  trees  for  a speclflc  s^plica- 
tion.  Most  resource  editor  programs  produce  three  output  flies.  One 
flle  has  a file  type  of  .DEF  and  is  used  onfy  by  the  resource  editor  pro- 
gram onfy  to  describe  the  layout  of  the  resource  flle.  llie  second  flle  has 
the  flle  type  of  .RSC  and  is  the  actual  resource  flle.  The  last  flle  is  a C 
header  flle  (flle  type  H),  which  contains  defined  constant  names  for 
the  index  of  each  named  object 

At  this  point  you  should  experiment  with  the  resource  editor 
program.  Try  the  various  flag  and  state  options  for  the  different  object 
types.  Create  a flee  tree,  and  place  all  of  the  objects  in  it  Then 
compare  similar  objects  to  see  what  makes  them  different  For  ex- 
ample. the  TEXT  and  STOING  objects  have  different  capabilities.  Also 
play  with  the  PTMPLT,  PVALID,  and  PTEXT  fields  of  an  EDIT  object 
You  will  notice  immediate  changes  with  the  PIMPLT  and  PVALID 
fields.  The  PTEXT  field  has  no  effect  until  you  use  the  resource  file 
in  a program. 

The  set  of  sample  programs  in  the  next  chapter  should  clarify  how 
these  objects  are  used  and  how  the  resource  editor  program  Interfaces 
with  your  application  program.  The  first  sample  program.  FORM,  uses 
the  dialog  box  just  created.  Then,  we  move  on  to  the  use  of  menus 
and  interacting  with  the  mouse  to  select  objects  in  the  menu.  Finalfy, 
you  create  a program  that  allows  you  to  display  files  on  the  screen. 


CHAPTER  TEN 


Resourceful 

Programming 


Previous  chapters  have  covered  what  the  A£)S  does,  its  primary  data 
structures  (the  object  and  object  trees),  and  the  resource  editor 
program.  How  to  create  a dialog  box,  one  of  the  several  types  of  object 
trees  that  can  be  created  with  the  resource  editor  program,  has  b^n 
demonstrated.  This  chapter  shows  how  to  use  this  information  in  an 
actual  application. 


Program  FORM 


Program  FX3RM  is  a demonstration  program,  that  utilizes  the  dialog 
box  created  in  the  last  chapter.  With  this  program,  you  are  able  to 
experiment  with  some  of  the  topics  mentioned  in  Chapter  9.  A few 
new  overhead  procedures  are  required  the  AE^.  Take  a look  at 
function  maln()  in  program  FX)RM  (see  Listing  10-1).  The  initialize 
GEM  Access  section  is  the  same  as  that  of  aU  other  programs  covered 
thus  far.  The  £q)pUcation-speciflc  routines  start  with  a call  to  the 
function  rerc_load( ).  This  is  an  AES  function  that  causes  the  AES 
to  load  a resource  file  into  memoiy  and  keep  track  of  the  objects 
loaded.  The  basic  process  for  an  application  using  a resource  file  is 
to  load  the  resource  file  into  the  AES  memoiy.  locate  the  tree  (array) 
you  want  to  use,  and  use  the  rsrc-firee( ) function  to  have  the  AES 
release  the  memory  used  for  the  resource  file  when  the  program  ends. 
The  isrc-load( ) function  returns  1 if  the  load  was  successful  or  0 if 
there  was  an  error  during  loading.  The  system  can  crash  if  you  tiy  to 
access  your  resources  without  having  the  resource  file  loaded.  In 
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Listing  10-1  Program  FORM 

/»»»»»»»»»»»»»»»»»»»»»»»»•»»»»»»»»»»»»»»»••»»•»»»»»»••»••»»»»»»»»»•»•»• 
rORM.C  Dialog  box  and  form  domonstration  program 

This  program  demonstrates  the  use  of  a dialog  box  to 
request  information  from  the  user. 


System  Header  Files  & Constants 


ttinciude 

<stdlo.h> 

tiinciude 

<osblnd.h> 

ttinciude 

<gemdefs.h> 

ttinciude 

<obdefs.h> 

ttdefine 

FALSE  0 

ttdef  ine 

TRUE  II 

Standard  ID 
GEMDOS  routines 
GEM  RES 
GEM  constants 


GEM  Rpplication  Os/erhead 


Declare  global  arrays  for  VDI. 
typedef  Int  WORD; 

WDRD  contrl(12], 

intout[120],  intin[120], 
ptsin[120],  pt8out[120]; 


14DRD  is  16  bits 
VDI  control  array 
VDI  input  arrays  */ 
VDI  output  arrays 


UDRD  sc  reeru.uhand  i e , 

scr een_phand 1 e , 
screeo.rez, 
coior^creen, 
x^ax, 
y-max; 


virtual  screen  uorkstation 
physical  screen  uorkstation 
y*  screen  resolution  0,1,  or  2 
y*  flag  if  color  monitor  *y 
y*  max  X screen  coord  *y 
y*  max  y screen  coord  *y 


/#««#««##«««««##«««««««««##«««#«««####«#««######««# 
Rpplication  Specific  Data 

*#«#«)(«##«»«««##««««««»«###«####«#«#«##««»«»«««#««/ 


Winclude  "form-h"  y^  resource  header  file  *y 

char  iast-name[16], 
first.jiame[ll] , 
birth.jiate[7] , 
home^ge[3] ; 


GEM-related  Functions 
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Uatiiig  10-1  (contiiiaed) 

UORO  operL-vuork(phys_handle) 

UORO  phys-handie; 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys_handls  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

UORO  work_ln[ll], 

uork_jout[57] , 

new-handle;  handle  of  workstation  »/’ 

Int  1; 


for  (1=0;  1 < 10;  1++) 
worl<^n[l)  = 1; 
worl<_ln[10]  = 2; 
nsw_handle  = physJnandle; 
v^pnvwk(work-J.n,  &new_handle,  workjout]; 
return(new_handle) ; 


set  for  default  values 


/*  use  raster  coords 

USB  currently  open  wkstation  */ 


SBt_ggrBHn__fl  titir  ( ] 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screen_vhandle. 

Output:  Sets  x_max,  y_max,  color_jscreen,  and  screen^rez. 

{ 

UORO  workout  [57]; 

vq_extnd[screerL_vhandle«  0«  workout]; 
x_max  = work^ut[0]; 
y_max  = workout  [1]; 

8creen_rez  = Getrez();  /»  0 = low,  1 = med,  2 = high 

color_screen  = (screen_rez  < 2);  /*  mono  2,  color  0 or  1 

> 

Rppllcation  Functions 
lnlt_form( ) 

Function:  Initialize  text  pointers  for  entry  form. 

Input:  None.  Resource  file  must  be  loaded. 

Output:  Sets  form  pointers. 

{ 

OBJECT  xbox^ddr; 
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Usting  10-1  (contiiuxed) 

get  address  of  dialog  box 

rsrc-jgaddr(0,  ENTRYBOX,  &box_jaddr); 

set  addresses  and  lengths  of  text  input 

((TEDINFO  »}box_addr(LNflME].cb-5pec)->te-ptext  = last^ame; 
((TEDINFO  *)box-addr[LNflME],ob-spec)->te-txtlen  = 16; 

((TEDINFO  »)box_^ddr(FNflWE].ob_^pec)->te_ptext  = first^name; 
((TEDINFO  »)box-jaddr(FNflWE].ob-spec)->te_txtlen  = 11; 

((TEDINFO  ») box_addr[ BIRTHDAY ].ob_spec)->te-p text  = birth-date; 
((TEDINFO  i»)box-addr[BIRTHDAY].ob_spec)->te-txtlBn  = 7; 

((TEDINFO  »)box^ddr(HDMEAGE].obL-spec)->te-ptext  = homa^ge; 
((TEDINFO  »]box^ddr(HCMERGE].ob^pBc)->tB_txtlen  = 3; 

return; 

} 

get_form( ] 

Function:  Display  dialog  box  to  get  data  from  user. 

Input:  None.  Resource  file  must  be  loaded. 

Output:  Returns  index  of  object  used  for  exit. 

Dialog  box  objects  selected  and  filled. 

{ 

UORD  xbox,  ybox,  hbox,  ubox; 

140RD  smalix,  smaiiy,  smailu«  smallh; 

I40RD  exit-object; 

OBJECT  ^box_addr ; 

get  address  of  dialog  box 

rsrc.jgaddr(0,  ENTRYBOX,  &box^ddr); 

show  initial  text  entry  v/alues 

printf  ( "^nLast  Name  - Address:  9(Blx,  Length:  %2d^n", 

((TEDINFO  »)box-addr[LNAME].ob-spec)->te_ptext, 

((TEDINFO  »)box-jddr(LNAriE].otLJspec)->te-txtien); 
printf( 'First  Name  - Address:  %Bix^  Length:  %2dNn”, 

( (TEDINFO  »)box^ddr[FNAME]  .ob^pec)  ->te-ptext, 

( (TEDINFO  *)box^ddr[FNAME]  .ob^pec) ->te-txtien) ; 
printf ( •Blrthdato  - Address:  a^Oix,  Length:  aj2d\n*, 

((TEDINFO  »)box.jaddr(BIRTHDAY].oh.j3pec)->te_ptBxt, 

( (TEDINFO  *)box.-addr(BIRTHDAY].ob.jBpec)->tB-txtion); 
printf  ( "Years  - Address:  SiOlx,  Length:  X2d\n", 

( ( TEDI NFO  * ) box-addr [ HDMEAGE ] . ob-spec ) - > te_p  tex  t , 

((TEDINFO  »)bDx_addr(HOMEAGE]. ob-spec) ->te_txtlen); 
Craucin( ) ; 
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Listing  10-1  (continned) 

clear  entry  screen 

*(((TEDINFQ  *)box«^ddr[LNftME] -ob-^pec) ->te_ptext)  =0; 
»(((TEDINFO  »)bo>c-addr[FNflME].ob_£pBc)->t8-ptext)  = 0; 
»(((TEDINFO  »)bo>cjaddr[BIRTHDflY].ob_8pec)->to_ptoxt)  = 0; 
»(((TEOINFO  »)box_addr[H0MEftGEl.ob-3pec)->te-ptext)  = 0; 
box^ddr[INCl]  .ob^tate  s NORMRL; 
box^ddr[INC2].ob^tate  = NORMRL; 
box^ddr[INC3].otLJ3tate  = KQRMflL; 
box-^ddr[INC4]  .ob^tate  = NQRnRL; 
box-jaddr[HDBl).ob^tate  = NORMftL; 
box-flddr[H0B2J.ob^tate  = NORMAL; 
box^ddr[HQB3].ab__state  » NORMAL; 
box-^ddr[H0B4].ab_jstate  & NORMAL; 

get  size  and  location  of  a box  centered  on  screen 
for(n-j:enter(box-addr,  &xbox,  &ybox,  &ubox,  &hbox); 
smallx  = xbox  + (ubox  ^2); 
smally  « ybox  + (hbox  >*2); 
smallu  = 0; 
smallh  = 0; 

reserve  area  on  screen  for  box  display 
form-dial (FMD-START, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

/*  drau  an  expanding  box 
form-dial (FMD-BROW, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

/»  drau  dialog  box 

objC-drau(box-addr,  ENTRVBOX,  10,  xbox,  ybox,  ubox,  hbox); 
handle  dialog  input 

exit-jobject  s forcn-do(box_addr,  LNAME); 

drau  a shrinking  box 
f orm-d 1 a 1 ( FMD_SHRI NK , 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

/»  reserve  area  on  screen  for  box  display 
form-dial (FMD-FINISH, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

y*  unselect  exit  object  for  next  time 

box-addr[exit-object] .ob-state  = NORMAL: 
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UstinglO-l  (contlntied) 

return(exi  t^bject) ; 

> 

shoui— info( ) 

Function:  Shou  information  entered  into  dialog  box. 
Input:  None.  The  dialog  box  objects  must  be  selected. 

Output:  None. 

{ 

OBJECT  »form_addr; 

get  base  address  of  dialog  box 

rsrcugaddr(0,  ENTRY60X,  &form_addr); 

/*  display  settings 

v.jcirul<(screen.vhandie) ; 
uucurhome(screen_vhandie) ; 


prlntf("Name  : %s  S{s\n", 

C (TEDINFO  »)form.jaddr[FNRWE] .ob_spec)->te_ptext, 

( (TEDINFO  *)fornuaddr[LNftME]  .cb.jBpBc)->tB_ptaxt) ; 

printf ( "Date  of  Birth  : Ji^sNn", 

((TEDINFO  » ) f ontLjaddr [ B IRTHDflV ] . ob_spec ) - > te«p tex t ) ; 
prlntf(  "Years  at  Current  Rddress:  3Js'^n* , 

( ( TEDINFO  » ) f ornLjaddr [ HOMEftGE ] . ob_spec ) - > te^^ text); 
printf( "Income  Level  : "); 

if  (form^ddr[INCl].ob^tate  & SELECTED) 
prlntf( "Under  $15,000"); 
else  if  (form.jaddr[INC2]  .ob^tate  & SELECTED) 
prlntf( "$15,000  - $24,999"); 
else  if  (fornLjaddr[INC3].ob.j5tate  & SELECTED) 
prlntf( "$25,000  - $49,999"); 
else  if  ( form.jaddr[INC4] .ob^tate  & SELECTED) 
printf( *$50,000  and  over*); 


printf ( "'^nHobblos  : “); 

if  (fornLjaddrtHOBlJ.ob-state  & SELECTED) 
prlntf( 'Skiing  *); 

if  (fornuaddr[K0B2].ob.jstate  & SELECTED) 
printf( "Tennis  "); 

if  (for{Tuaddr(K0B3] .ob^tate  & SELECTED) 
printfC "Music  "); 

if  (forriL.addr(K0B4] .ob.jBtatB  & SELECTED) 
prlntf( "Swimming  *); 

prlntf  ( ■'*^nNnPress  any  key  to  continueNn" ) ; 

Craucin( ) ; 
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Usting  10-1  (contimied) 

return; 

> 


Main  Program 

maln( ) 

{ 

int  ap-id;  application  Inlt  uerlfy 

UDRD  gr^char*  gr_hchar«  values  for  VDI  handle 

gr_ubox , gr Jibox ; 

UDRD  ret^ode;  form  exit  code 

Initialize  6Eh  Recess 

ap.ld  s appl^nltO;  Initialize  RES  routines 

If  (ap-J.d  < 0)  no  calls  can  be  made  to  RES 

{ use  GEMDDS  *■' 

Cconws( Initialization  Error.  <»**^n'); 

Cconus( "Press  any  key  to  continue. ^n" ) ; 

Craucln( ) ; 

exlt('l);  set  exit  value  to  shou  error 

) 

screeruphandle  = Get  handle  for  screen  */ 

graf Jiandle(&gr^char,  &gr_hchar,  &gr_ubox«  &gr_hbox]; 
screerL.vhandle  = open„vuork(scre8n_phandle) ; 
set.j5creBnLjattr( ) ; Get  screen  attributes 


Rppllcatlon  Specific  Routines 

if  ( !rsrc_load( ■FORM.RSC" ) ) trouble  loading  resource  file 

{ 

forfn-ualert(l,  "[0][Could  not  load  file  FORM. RSC| Program  terminating. ..] [OK] ” ); 
exit(l) ; 

) 

allou  user  to  skip  form  Initialization  *y 

printf ( '^n^nProBB  *1*  to  initialize  form^n']; 
if  ( (CrauclnO  & 0x7f)  ==  'I‘) 
lnlt_form( ); 
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UstinglO-l  (contlniied) 

uhlle  ( (ret-coda  = get.form( ) ) !-  QUIT) 

if  (ret^ode  •=  CLEftR) 
shouLJ.nfa( ) ; 

> 

Program  Clean-up  and  Exit 

rsrc_f ree( ) ; release  memory  for  resources 

v^isv;uk(screen_vhandie) ; close  workstation 

appi_exlt();  z’*  end  program 

> 

/»«»««»»»«»««««/ 


FORM,  the  program  uses  the  i8rc_load()  function  to  load  the 
resource  file.  The  result  of  this  function  is  tested.  If  the  resource  file 
has  not  been  loaded  property,  the  f6im_alert( ) function  is  called  to 
tell  the  user  an  error  has  occurred. 

The  form_alat( ) function  causes  an  alert  box  to  be  displayed.  This 
function  has  two  parameters.  The  first  parameter  indicates  the 
default  exit  button  for  the  form.  A value  of  0 means  no  default  button. 
A value  of  1.  2.  or  3 indicates  the  first  second,  or  third  button, 
respectively.  The  second  parameter  is  a string  defining  the  format  of 
the  alert  box.  This  string  is  divided  into  three  fields  with  each  field 
surrounded  by  square  brackets.  The  first  field  contains  a digit  for  the 
icon  type  to  use.  T^pe  0 means  no  icon.  Type  1 means  the  Note 
icon,  vidiich  is  an  exclamation  point  Type  2 is  the  Wait  icon,  which 
is  a question  mark.  Type  3 is  a stop  sign  called  the  Stop  icon.  The 
second  field  is  the  message  text  The  alert  box  can  have  up  to  five  text 
lines,  each  with  up  to  40  characters.  In  this  field,  a vertical  bar 
indicates  the  separation  of  one  line  from  the  next  In  the  program, 
the  text  “Could  not  load  file  FORM.RSC”  forms  the  first  line,  and 
“Program  terminating . . ."  forms  the  second  line.  The  third  field  of  this 
second  parameter  indicates  the  text  used  in  the  exit  buttons.  The  text 
for  each  button  is  separated  by  a vertical  bar.  The  text  for  each  button 
may  contain  no  more  than  20  characters.  In  FORM,  there  is  only  one 
exit  button  labeled  “OK."  The  user  has  no  choice  but  to  end  the 
program. 

Once  the  resource  file  has  been  loaded,  the  program  can  begin  its 
processing.  The  first  process  in  FORM  is  to  initialize  the  default 
values  used  in  the  dialog  box.  To  assist  you  in  experimenting  with 
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the  resource  file  and  objects,  FDRM  gives  you  the  option  of  initializing 
the  dialog  box  or  skipping  the  initialization.  Initialization  can  be  used 
to  set  the  storage  size  and  location  of  the  data  to  be  entered.  The 
TEDINFO  structure  has  the  te_ptezt  field,  which  points  to  the  entered 
data  and  field  te-txtlen,  which  contains  the  length  of  this  data  In 
the  resource  editor  program,  the  PTEXT  field  of  em  editable  object  was 
filled  with  underscores  to  set  the  length  of  the  editable  text  (te-txtlen). 
In  addition  to  setting  the  length,  the  underscores  also  allocate  the 
memory  space  required  to  store  the  text  string.  The  teL.ptezt  field  is 
only  a pointer  and  does  not  know  if  that  location  is  reserved  for  the 
entered  string.  If  the  space  is  not  reserved,  the  AE^  starts  to  write 
over  other  data  in  memory.  One  method  of  avoiding  this  problem  is 
to  use  the  underscore  in  the  resource  editor  program.  The  other 
method  is  to  override  the  values  created  by  the  resource  file  by  simply 
resetting  the  appropriate  fields  in  the  TEDINFO  structure.  For  ex- 
ample, a program  can  set  the  te-txtlen  field  to  whatever  string  length 
is  required  and  can  set  the  te.ptext  field  to  point  to  a string  or  space 
aUocated  through  Mallocf ).  A word  of  warning:  the  te-ptext  field 
must  point  to  a memory  location  reserved  for  the  entered  string  and 
the  te-txtlen  must  have  a value  less  than  or  equal  to  the  amount  of 
space  reserved.  If  these  two  conditions  are  not  met,  you  may  alter 
portions  of  your  program  that  should  not  be  changed. 

After  the  initialization  is  a loop  that  displa3rs  the  dialog  box  and 
has  the  user  enter  the  information.  If  the  OK  Exit  button  Is  used,  the 
data  entered  is  shown  and  the  loop  continues.  If  the  Clear  Form 
button  is  used,  the  form  Is  reset  and  the  loop  continues.  If  the  Quit 
button  is  used,  the  loop  exits  and  the  program  ends.  The  end  of  the 
program  uses  the  isrcL.firee( ) function  to  release  the  memoiy  used  by 
the  resource  file. 

Function  init_form( ) simply  starts  the  addresses  and  lengths  of  the 
text  strings  to  be  entered  through  the  dialog  box.  The  fimction 
init-formf ) in  the  application  functions  is  an  example  of  how  to 
access  objects  within  a tree.  Because  all  object  trees  are  stored  as 
arrays,  the  program  needs  the  base  address  of  the  array.  The  base 
address  of  the  tree  is  obtained  through  the  xsrc-gaddr()  function. 
This  function  has  three  parameters.  The  first  parameter  indicates  the 
object  lype  to  be  located  (see  Table  10-1 ).  The  second  parameter  is  the 
index  number  of  this  structure.  The  last  parameter  is  an  address  of 
a pointer.  The  address  of  the  located  structure  is  placed  in  this 
parameter  upon  return.  In  FORM  the  type  of  data  structure  searched 
for  is  a tree.  It  has  an  index  number  ENTRYBOX  defined  in  the  header 
file  for  the  program.  The  address  of  the  tree  is  put  into  variable 
box,  addr.  Note:  Make  sure  that  the  header  file  FORM.H  is  Included 
in  the  program.  If  it  is  not  included,  the  program  does  not  know  the 
index  values  of  the  object  arrays. 
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Table  10*1:  Function  rsrc-gaddrf  ) Data  Stractore 


Parameter  Value 

Type  of  Data  Structure 

0 

Tree 

1 

OBJECT 

2 

TEDINFO 

3 

ICONBIiC 

4 

BITBLK 

5 

String 

6 

Image  data 

7 

ob-spec 

8 

te_ptext 

9 

te-ptmplt 

10 

teLpvalid 

11 

Ib^mask 

12 

ib-p<lata 

13 

lb_ptext 

14 

bL4>data 

15 

ad_frstr— address  of  a pointer  to  a free  string 

16 

ad_frlmg— address  of  a pointer  to  a free  image 

Once  tsrCL^addrC ) returns  the  value,  bosLoiddr  will  have  the  base 
address  to  an  array  that  contains  the  objects  in  the  ENTRYBOX  tree. 
Therefore,  all  the  objects  in  the  ENTRYBOX  tree  can  be  accessed 
using  the  index  values  defined  in  the  header  file.  The  next  eight  lines 
initialize  the  form  to  make  sure  that  the  length  and  initial  text  are 
set  properly.  Each  of  the  text  entiy  fields  is  of  type  GJFTEXT.  In 
Chapter  9,  an  object  of  this  type  has  an  OBJECT  structure  and  a 
TEDINFO  structure.  In  init_fonii( ),  the  variable  boz_addr[LNAIdE]. 
obu-spec  refers  to  the  ob_spec  field  of  the  OBJECT  structure  in  the 
array  for  the  last  name  entiy.  For  a GJFTEXT  object,  the  ob_spec  field 
points  to  a TEDINFO  structure,  so  that  a ^e  cast  of  a TEDINFO 
pointer  is  used  for  the  ob_spec  field.  Within  the  TEDINFO  structure, 
the  teL.ptext  field  is  initialized  to  point  to  an  empty  string.  This  is  an 
example  of  how  to  get  quite  confused  if  you  don’t  keep  the  objects  and 
their  types  organized.  With  the  liberal  use  of  object  names  and  good 
comments  in  the  program,  you  should  be  able  to  keep  track  of  your 
program’s  flow. 

The  next  function  listed,  get_form( ),  provides  the  series  of  routines 
required  to  display  a dialog  box,  get  data  from  the  user,  and  remove 
the  dialog  box  from  the  screen.  Displa}dng  a dialog  box  through  the 
AES  follows  a neat  and  orderly  procedure.  First,  rsrc-gaddrf ) is  called 
to  get  the  address  of  the  object  tree.  Function  fbnn-center( ) is  called 
to  center  the  dialog  box  on  the  screen.  'The  dialog  box  does  not  have 
to  be  centered  and  can  be  placed  anywhere  you  like.  However,  a 
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centered  dialog  box  looks  better.  The  fonn-dlal( ) routine  Is  called  to 
perform  several  utility  functions.  The  first  time  it  is  called,  it  reserves 
the  part  of  the  physical  screen  where  the  dialog  box  is  to  appear.  This 
simply  prevents  anything  else  from  appearing  on  that  portion  of  the 
screen  until  the  dialog  box  Is  completed.  A second  call  to  fonn_dlal( ) 
draws  an  expanding  box,  much  like  the  one  displayed  when  a floppy 
disk  is  opened  to  display  the  directory.  Function  ot>|c_dxaw( ) Is  called 
to  draw  the  dialog  box  and  its  contents.  Function  fonn_^( ) turns 
control  over  to  the  AE^,  which  then  allows  the  user  to  Interact  with 
the  dialog  box.  When  the  user  satisfies  one  of  the  exit  conditions  (by 
pressing  the  Exit  button  or  the  Return  kQr  if  a default  button  was 
chosen),  l6xiii-do( ) returns  and  fonn_dial( ) are  called  a third  time  to 
draw  a shrinking  box.  Function  foxnL.dlal( ) Is  called  one  more  time 
to  free  the  screen  area  and  redraw  the  screen  at  that  location. 

In  get-fbxm( ),  the  first  thing  needed  is  the  address  of  the  dialog 
box.  Next  for  demonstration  purposes,  the  current  values  In  the  text 
fields  are  shown.  These  values  are  then  cleared  from  the  entry  form. 
The  states  of  the  selection  boxes  for  Income  level  and  hobbles  are  all 
set  to  NORMAL  so  that  no  buttons  are  shown  as  selected.  It  Is 
Important  to  Initialize  the  values  of  entry  fields  before  displaying 
forms  such  as  this. 

The  function  fonn_center( ) is  then  called.  It  is  given  the  address 
of  the  dialog  box  and  returns  the  x and  y coordinates  and  width  and 
height  of  the  box.  The  coordinates  are  screen  coordinates  measured 
in  pixels.  Once  the  program  knows  where  the  dialog  box  Is  located, 
the  first  call  to  form  dialQ  can  be  made.  The  first  parameter  for 
form_dial( ) determines  what  type  of  action  is  to  be  performed  (see 
Table  10-2).  The  values  smallz,  smally,  smallw,  and  smallh  are  not 
used  in  this  call  They  are  provided  here  as  placeholders  and  are  used 
in  other  calls  to  fonn-dial( ).  The  variables  rdM»c.  yboz,  wbox.  and  hbox 
determine  the  size  and  location  of  the  dialog  box.  These  values  are 
used  to  reserve  screen  space  for  the  dialog  box. 


Table  10-2:  Function  fornoudialf  ) Action  Fla^ 


Constant  Name 

Value 

Action 

FMD-START 

0 

Reserve  screen  space 

FMD-GROW 

1 

Draw  expanding  box 

FMD_SHRINK 

2 

Draw  shanking  box 

FMD-FINISH 

3 

Release  screen  space 

The  next  call  to  form-dial( ) actually  draws  the  expanding  box  using 
the  defined  value  FMD_GROW  as  the  first  parameter.  The  variables 
smallz,  small^.  smallw,  and  smallh  contain  the  size  and  location  of 
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the  starting  box  size.  Function  fomi-dial( ) draws  the  image  of  a box 
expanding  from  its  small  size  and  location  to  Its  large  size  and 
location.  The  size  and  location  of  the  small  and  large  boxes  are 
completely  arbitrary,  and  you  may  use  any  values  that  are  appropriate 
to  your  program.  In  FORM,  the  small  box  Is  located  at  the  center  of 
the  screen  with  no  height  or  width. 

The  next  step  Is  to  draw  the  dialog  box  on  the  screen  using 
oti|e.dn(w( ).  Given  a tree  address  and  the  Index  to  the  first  object  to 
draw  (the  first  two  parameters).  otjc_drawt ) will  draw  the  object  and 
any  number  of  levels  of  children  (the  third  parameter)  for  that  object 
The  last  four  parameters  Indicate  the  clipping  rectan^e  to  use.  The 
clipping  rectangle  in  this  case  is  the  same  size  as  the  dialog  box.  An 
object’s  level  in  a tree  is  the  distance  from  the  root  to  the  object  For 
example,  the  root  Itself  is  at  level  0.  The  children  of  the  root  are  at 
level  1.  The  children  of  those  objects  are  at  level  2,  and  so  forth.  Given 
a starting  index  value  (here  the  start  is  the  root  but  it  can  be 
anywhere),  otje-diawf ) draws  the  specified  number  of  levels  from 
that  point  on.  The  value  10,  used  in  FORM,  is  a relatively  large  value 
and  should  cover  most  dialog  boxes  created.  However,  any  value  can 
be  used.  A value  of  32  or  64  should  be  sufficient  to  cover  any  tree  you 
woidd  create.  Function  o1^c_dzaw( ) is  quite  flexible  in  what  it  draws. 
By  passing  the  address  of  a tree,  it  can  draw  the  entire  tree,  the  first 
few  levels,  onty  one  object  or  a few  objects  in  the  middle  of  the  tree. 

Once  the  dialog  box  is  displayed  on  the  screen,  the  program  is  reacty 
to  accept  data  from  the  user.  The  A£^  function  lbmi_do( ) causes  the 
AES  to  take  control  of  the  ^tem  and  handles  user  Interaction  with 
the  dialog  box.  The  AES  controls  what  can  be  changed,  edited,  or 
selected  based  upon  the  flags  and  states  for  each  object  When  the 
user  selects  the  Exit  button,  function  fomi-do( ) ends.  The  index  of 
the  exit  object  selected  is  the  value  returned  by  fotm.do( ).  If  the  user 
pressed  the  Return  key  to  exit  the  Index  of  the  default  exit  object  is 
returned.  In  get_form(),  the  Ind^  of  the  exit  object  is  saved  in 
variable  exit-object 

When  the  user  has  completed  entering  the  information  in  the  dialog 
box,  the  eq>plication  should  remove  the  box  from  the  screen.  In  this 
case,  fonn-dial( ) is  called  to  draw  a shrinking  box  and  then  called 
again  to  release  (he  area  on  the  screen  used  ty  the  dialog  box. 

The  final  action  performed  in  routine  getJormO  is  to  reset  the 
state  of  the  exit  object  When  function  forni-do( ) returns  control  to 
the  program,  all  the  object  states,  flags,  and  data  are  left  unchanged 
to  aUow  the  program  to  examine  the  exit  condition  and  state  of  the 
dialog  box.  When  a user  selects  an  adt  object  that  object  is  put  into 
its  selected  state  (reverse  colors).  The  next  time  the  dialog  box  is 
displ^ed,  this  exit  object  appears  selected.  To  avoid  this  confusion, 
the  exit  object  must  be  set  back  to  its  normal  state.  In  get_fonn( ), 
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once  the  dialog  box  is  removed  from  the  screen,  the  state  of  the  exit 
object  is  restored  to  NORMAL.  After  resetting  the  state  of  the  exit 
object  get-form( ) returns  the  index  of  the  exit  object  to  the  calling 
function. 

Function  diow-infoO  displays  the  values  sdected  by  the  user. 
Primarily,  the  function  demonstrates  accessing  the  various  fields  of 
the  objects  in  the  dialog  box  and  how  to  interpret  this  information. 

Program  FORM  is  relatively  simple  compared  to  some  of  the 
programs  presented  later.'  It  is  important  to  understand  the  fidd 
access  method  and  how  an  index  is  used  to  access  a particular  object 
All  these  features  are  used  in  the  remaining  programs.  Ei^rlment 
with  program  FORM.  First  investigate  the  Adds  of  the  OBJECT  and 
TEDINFO  structures.  Then  change  the  template,  validation,  and  text 
strings  through  FORM  and  through  the  resource  editor.  Finalfy,  tiy 
changing  the  objects  in  the  dialog  box  or  even  creating  dialog  boxes 
of  your  own.  FORM  is  a sample  program  to  familiarize  you  about  how 
objects  are  related  between  the  program  and  the  resource  file. 


AES  Naming  Conventions 


There  is  a certain  pattern  In  the  AES  function  names.  The  AES  has 
a huge  number  of  functions  that  are  divided  into  libraries,  or  group- 
ings of  functions  that  have  something  in  common.  Ihe  applications 
manager  deals  with  communications  between  applications  and  with 
initializing  and  exiting  £q>pllcatlons.  All  applications  manager  routines 
begin  with  “sq^pL.”.  The  event  manager,  or  event  library,  contains 
functions  to  handle  events  that  occur  during  the  processing  of  a 
program.  Events  control  the  flow  of  all  programs.  EXnent  manager 
routines  b^in  with  “evnt_”.  The  file  selector  manager  provides  a file 
selector  dialog  box  and  controls  its  activities.  The  file  selector 
manager  consists  of  one  routine,  ftd_iiqnit( ) discussed  at  the  end  of 
this  chsq)ter.  The  form  manager  controls  forms:  dialog  boxes,  alert 
boxes,  and  error  boxes.  All  of  its  routines  begin  with  “f6rm_”.  The 
graphics  manager  handles  basic  graphic  output  used  by  the  AES.  It 
contains  the  actual  routines  that  draw  growing  and  shrinking  boxes. 
It  also  allows  the  application  to  make  changes  in  how  the  mouse 
cursor  is  displayed.  All  these  routines  begin  with  “gra£_".  The  menu 
manager  controls  the  menu  bar,  the  menu  Item  appearance,  and 
registers  desk  accessories  in  the  menu.  Its  routines  begin  with 
“menu-”.  The  object  manager  allows  an  application  to  find  objects, 
draw  objects,  change  and  reorder  an  object  tree,  and  add  or  delete 
objects.  All  of  Its  routines  begin  with  “obJc_”.  The  resource  manager 
handles  loading  and  freeing  of  resource  space  In  memory  and  deter- 
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mines  addresses  of  resotirce  objects.  All  of  Its  routines  begin  with 
“rsrc_".  The  scrap  manager  Is  used  to  write  Information  out  to  a 
scrap  file.  It  contains  two  functions:  scip-readf ) and  scxp-writie( ). 
Flnalfy.  the  window  manager  handles  the  creation,  deletion,  opening, 
and  closing  of  windows,  as  well  as  window  maintenance.  Its  routines 
begin  with  “wind-". 


Using  Menus 

The  next  two  programs  use  a resource  file  called  MENU.RSC.  This 
resource  file  contains  two  trees,  a menu,  and  a dialog  box.  A menu  is 
also  based  on  an  object  tree.  The  menu  bar  is  the  root  Each  menu 
title  is  a child  of  the  root  The  entries  In  each  menu  are  children  of 
the  menu  title. 

Load  the  resource  editor  program,  and  drag  a menu  icon  into  your 
work  area.  Name  this  tree  MAINMENU.  Double-click  this  menu  icon 
to  open  it  As  mentioned  in  Chapter  9.  the  menu  bar  should  always 
have  the  two  titles  Desk  and  PUe.  Click  the  Desk  option  to  display 
this  menu.  On  the  first  line,  the  option  is  labeled  "Your  message  here.” 
The  second  entry  is  a line  of  disabled  dashes.  The  next  six  entries  list 
“Desk  Accessory  1"  through  “Desk  Accessory  6.”  The  six  desk  acces- 
sory entries  are  used  by  the  AES  menu  manager.  When  a desk 
accessory  is  in  the  ^tem,  the  menu  manager  changes  one  of  the 
entries  in  the  Desk  menu  to  the  title  of  the  accessory.  This  is  done 
without  any  action  from  your  program.  The  first  entry  in  the  Desk 
menu  is  usually  changed  to  read  “About  Program..."  This  entry  is  used 
to  initiate  a dialog  box  that  provides  infomiatlon  about  the  applica- 
tion. Under  the  File  title,  there  is  only  one  option  called  Quit  The 
menu  part  box  should  contain  at  least  four  items;  a title  object,  an 
entry  object  a disabled  dash,  and  a box. 

For  the  MENU.RSC  file.  3^u  need  to  change  some  of  the  existing 
menu  entries  and  create  a new  menu  (see  Figure  10-1).  To  create  a 
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new  menu,  drag  a TITLE  object  from  the  parts  box  to  the  menu  bar 
and  place  it  to  the  right  of  the  Pile  title  Double-click  it  and  change 
the  text  to  read  “Sample."  Make  sure  you  Include  the  space  before  the 
word  so  that  it  doesn’t  run  into  the  File  title.  Click  OK  and  the  new 
menu  title  is  displayed. 

Click  the  Sample  title  once  to  select  it  The  title  Is  displayed  in 
reverse  colors  and  has  an  empty  entiy  box  underneath  it  This  box 
holds  all  entri^  for  the  menu,  so  it  must  be  long  enough  and  wide 
enough  for  these  entries.  Resize  the  Sample  entry  box  so  that  it 
contains  about  three  lines.  The  exact  size  is  not  that  important  right 
now  since  you  can  resize  the  box  again  later. 

To  make  an  entry  in  a menu,  drag  an  ENTRY  object  from  the  parts 
box  to  the  first  line  of  the  menu’s  entry  box.  The  left  edge  of  the 
ENTRY  object  should  be  just  Inside  the  left  edge  of  the  entry  box. 
Repeat  this  procedure  two  more  times  on  the  next  two  lines  for  the 
Sample  menu.  You  now  have  a menu  with  three  titles  called  Desk, 
File,  and  Sample.  Under  the  Sample  menu  there  is  an  entry  box  with 
its  first  three  fines  reading  “ENTRY.” 

To  change  the  text  of  an  entry,  double-click  it,  and  change  the  text 
line.  Double-click  the  top  entry,  and  label  it  “Door  Bell."  For  aesthetic 
purposes,  most  menu  entries  have  at  least  two  spaces  before  the  text 
The  first  space  is  used  to  hold  a check  mark  (If  necessary),  and  the 
second  space  is  used  to  allow  room  between  the  check  mark  and  the 
text  Change  the  text  of  the  second  entry  to  “Disable  Door  Bell.”  and 
change  the  text  of  the  third  entry  to  “Uncheck  Item.”  For  the  third 
entry,  also  select  the  CHECKED  flag  to  turn  on  the  check  mark. 

Return  to  the  Desk  menu.  Change  the  first  entry  fine  to  read  “ A | 
About  MENU”.  The  letter  “A”  at  the  start  of  the  entry  signals  the  user 
that  the  Control-A  keyboard  entry  performs  the  same  function  as 
selecting  this  item  from  the  Desk  menu.  Go  to  the  File  menu  and 
change  the  Quit  option  to  read  “ Q | Quit”  The  user  is  able  to  press 
Control-Q  instead  of  clicking  the  Quit  option.  You  now  have  the 
completed  menu  (see  Figure  10-1). 

Close  the  menu  to  return  to  the  main  window.  Drag  a dialog  box 
to  the  work  area  and  call  It  INFOBOX.  This  is  the  dialog  box  displayed 
in  response  to  the  About  MENU  entry  In  the  Desk  menu.  Create  the 
text  using  STRING  objects  as  shown  in  Figure  10-2.  Add  a button 
with  the  OK  text  Make  sure  the  button  is  set  as  SELECTABLE, 
DEFAULT,  and  EXIT. 

The  final  step  in  creating  this  resource  file  is  to  name  the  objects 
used  in  the  program.  The  onty  objects  of  concern  in  this  file  are  in 
the  menu.  Return  to  the  menu  window  and  select  the  About  MENU 
entry  In  the  Desk  menu.  Name  this  object  INFO.  Go  to  the  File  menu, 
select  QUIT,  and  name  it  QUIT.  Select  the  title  for  the  Desk  menu  and 
name  it  DE^K  Name  the  File  menu  title  FILE.  The  Sample  menu  title 
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Program  flEHU 


This  program  demonstrates  the  use  of  a 
menu  within  an  application. 


OK 


Figure  10-2  Dialog  Box  INFOBOX  from  BfENU.RSC 


Is  to  be  named  SAMPLE.  Finally,  name  the  Door  Bell  entiy  as 
SAMPLE  1,  the  Disable  Door  Bell  entiy  as  SAMPLE2,  and  the  Uncheck 
Item  as  SAMPLES. 

This  completes  the  resource  file  for  programs  MENUl  and  MENU2. 
Save  this  resource  file  in  the  file  called  MENU.RSC. 


Program  MENUl 


Program  MENUl  provides  an  introduction  to  using  a menu  in  your 
program.  The  menu  bar  is  one  portion  of  the  screen  Image  handled 
by  the  AES.  A program  can  request  a new  menu  bar  to  be  displayed 
and  can  change  how  the  items  in  the  menu  are  displayed.  However, 
any  user  interaction  with  the  menu  is  handled  by  the  AES.  Whenever 
the  mouse  touches  one  of  the  menu  titles,  the  A£^  immediate^  takes 
control  and  displays  the  drop-down  menu.  The  AES  retains  control  of 
the  ^tem  until  the  mouse  button  Is  pressed.  Pressing  the  mouse 
button  can  signal  a menu  selection  if  the  mouse  Is  located  on  an 
active  menu  item.  Once  the  mouse  button  is  pressed  the  screen  image 
beneath  the  drop-down  menu  is  restored.  If  a menu  Item  Is  selected, 
the  AE^  communicates  the  selection  to  the  application  by  sending  it  a 
message  as  described  in  Chapter  9. 

Receiving  a message  is  an  event.  To  receive  the  message,  the 
program  has  to  wait  for  a message  event  to  occur.  Only  when  a 
message  event  is  received  should  the  program  tiy  to  read  a message. 
Waiting  for  a message  event  is  done  through  the  evnt_mesag( ) func- 
tion from  the  event  manager.  This  function  has  one  parameter— a 
pointer  to  an  array  of  eight  WORDs.  In  essence,  this  array  provides  a 
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16-byte  buffer  for  the  message.  The  message  buffer  has  a predefined 
format  depending  upon  the  type  of  message  sent  Element  0 of  the 
array  contains  the  of  message  sent  Element  1 Is  the  ID  number 
of  the  explication  that  originates  the  message,  dement  2 contains 
the  message  length  in  excess  of  16  bytes.  If  this  value  Is  0,  the 
message  is  less  than  or  equal  to  the  basic  16  bytes.  If  the  message  Is 
laiger  than  16  bytes,  the  value  In  element  2 is  equal  to  the  message 
length  minus  16.  In  any  case,  the  first  three  elements  of  the  16-byte 
message  buffer  are  always  used.  Any  excess  bytes  must  be  read  using 
the  qxl_read( ) function  described  in  Appendix  A.  The  meaning  of 
the  remainder  of  the  message  buffer  depends  upon  the  type  of  mes- 
sage sent  (see  Appendix  B for  description  of  messages). 

Program  MENUl  is  only  interested  in  one  type  of  message — a menu- 
sdected  message.  The  predefined  constant  MN-SELECTED  is  the 
message  type  used  to  indicate  that  a menu  item  has  been  selected  by 
the  user.  For  this  type  of  message,  element  3 of  the  message  buffer 
array  contains  the  Index  number  of  the  menu  title  object  Element  4 
contains  the  index  number  of  the  menu  Item  selected.  For  example, 
if  the  user  selects  Disable  Door  Bell,  element  3 has  the  index  number 
of  title  Sample,  and  element  4 has  the  index  number  of  the  entry 
Disable  Door  Bell. 

Look  at  program  MENUl  in  Listing  10-2.  In  function  main( ),  the 
initialization  is  the  same  as  in  program  FORM  except  that  the 
resource  file  loaded  is  MENU.RSC.  The  address  of  the  menu  tree  is 
retrieved  and  function  meno-barf ) is  called  to  display  the  new  menu. 
Function  menu_bar( ) has  two  parameters.  The  first  is  the  address  of 
the  menu.  The  second  is  whether  the  menu  is  to  be  di^layed.  In  some 
cases,  you  may  want  to  make  the  menu  bar  invisible  until  the  user 
performs  some  action  like  changing  disks. 

fJwHng  10-2  Program  MENU 

MENUl. C Menu  demonstration  program 


This  program  shows  the  use  of  menus  in  an  appiication. 


System  Header  Fiies  & Constants 


ttincluda  <stdio.h> 
ttinclude  <osbind.h> 
ttinclude  <gemdefs.h> 
liinciude  <abdefs.h> 


Standard  10 
BEMDOS  routines 
y*  GEM  flES  *y 
y*  GEM  constants  *y 
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iJaHng  10-2  (continued) 

tide  fine  FRLSE  0 

ttdefins  TRUE  !FftLSE 

QEtl  ^Application  Qverhead 


/»  Declare  global  arrays  for  VDI. 

typedef  int  WORD;  WORD  is  16  bits 

WORD  contrl[12],  VDI  control  array 

intout(120],  intin[128],  /*  VDI  input  arrays 

ptsin(12B],  ptsout[128];  VDI  output  arrays 


screea.vhandle. 

/* 

screen.43hand  le , 

/* 

screen.j~ez. 

/* 

color^creen. 

/* 

x^ax. 

/» 

y-jnax; 

/* 

virtual  screen  workstation 
physical  screen  workstation 
screen  resolution  0,1,  or  2 
Flag  if  color  monitor 
max  X screen  coord  */ 
max  y screen  coord 


Rppilcation  Specific  Data 


tl  include  'menu.h” 

char  ding^ong[]  = { array  for  Dosound 

0,  239,  1,  0,  7,  62,  8,  8,  130,  25, 

0,  63,  1,  1,  130,  40,  7,  63,  8,  0,  255,  0 

>: 


GEM- related  Functions 


WORD  operL.vwork(phy8^andie) 

WORD  phys^andle; 

Function:  This  function  opens  a virtual  workstation. 

Input:  physJiandle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

{ 

WORD  work.in(ll], 

uorl<^ut[57], 

neu-handle;  handle  of  workstation 

int  i ; 


I 
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Listiiig  10-2  (contizmed) 

for  (i  s 0;  I < 10;  1++) 
work«in(l]  = 1; 
uork«in[10]  = 2; 
neuL-handle  = physJiandle; 
v^pnvwk(uork.ln«  &neuiLjiandle 
return(nBULjiandle) ; 


sot  for  default  values 

use  raster  coords 
use  currently  open  ukstatlon 
uork^ut) ; 


set_scrBen_attr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screea_vhandle. 

Output:  Sets  x_jnax,  y^ax,  color^creen,  and  screen^ez. 

{ 

I40RD  uork.jout[57] ; 

vq-jBXtnd(8creen^vhandle,  0,  uorkuout); 
x^ax  s uork.jout[0] ; 
y.jnax  » uorloout[l]; 

screerLxez  = 6etrez();  0 = low,  1 = med,  2 = high 

color^creen  = (screeruxaz  < 2);  mono  2,  color  0 or  1 

} 

Rppllcatlon  Functions 

doud  1 a 1 og  ( box^  ndex ) 

UiORD  box^ndex; 

Function:  Display  a dialog  box. 

Input:  box^jaddr  = Index  of  dialog  box 

Output:  Returns  Index  of  object  used  for  exit. 

««««!(  ft 

{ 

UORD  xbox,  ybox,  hbox,  ubox; 

UORO  smallx,  smally,  smallu,  smallh; 

UORD  exlt.jobJect; 

OBJECT  ^boxwaddr ; 

get  address  of  box  */ 

rsrc^addr(0,  box^ndex,  &box.jaddr); 

get  slza  and  location  of  a box  centered  on  screen 
fornLjcenter(box^ddr,  &xbox,  &ybox,  &uibox,  &hbox); 
smallx  = xbox  + (ubox  ^2); 
smally  = ybox  + (hbox  ^2); 
smallu  = 0; 
smallh  = 0; 
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Usting  10-2  (continned) 

reserve  area  on  screen  for  box  display 
f orni_-di  al  ( TMO— STfiRT , 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

drau  an  expanding  box 
fortrujdial(FMDJGRGW, 

smalix,  smaily,  smallu,  smalih, 
xbox,  ybox,  ubox,  hbox); 

/«  draw  dialog  box 

objc^rau[box^ddr,  0,  10,  xbox,  ybox,  ubox,  hbox); 

y*  handle  dialog  input 

exit^bject  - fornLjdo(box_addr,  0); 

draw  a shrinking  box 
form_dlal(FMO_SHRINK, 

snaiix,  smaiiy,  smaiiw,  smaiih, 
xbox,  ybox,  wbox,  hbox); 

reserve  area  on  screen  for  box  display 
f orfR-d  ia  1 ( FMD-F  INI  SH , 

smaiix,  smaiiy,  smaiiw,  smaiih, 
xbox,  ybox,  ubox,  hbox); 


/*  reset  exit  object  state  to  unseiected 

box^ddr[exit^bJect]  .ob^tate  = NORKRL; 

return  [ ex  i t^bj  ect ) ; 


Main  Program 


main[ ) 

< 

int  ap^id;  application  init  verify 


UORD  gr^char,  grJichar, 
gr^box,  gr^box; 

new  data  variables 
OBJECT  ^msnuuaddr ; 
UORD  msg^uf[a]; 


values  for  VOI  handle 


y*  address  for  menu 
message  buffer 
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Listing  10*2  (continned) 

Initialize  GEM  Access 


ap.ld  = appl_lnlt();  Initialize  RES  routines 

if  (ap^id  < 0)  no  calls  can  be  made  to  RES 

{ /»  use  GEMDOS  »/ 

Cconus(  Initialization  Error.  <»*»^n"); 

Cconus( 'Press  any  key  to  continue. ^n' ) ; 

Craucin( ); 

exit('l);  set  exit  v/aiue  to  shou  error 

> 

screeo-phandie  = Get  handle  for  screen 

graf.Jiandie(&gr.j«ichar,  &gr^char,  &gr_ubox,  &gr^box); 
screerLJirhandle  = open^vucrkCscreen-phandle) ; 
setjscreen^ttrO;  Get  screen  attributes  »/ 


Rpplication  Specific  Routines 


if  (!rsrc-.ioad("MENU.RSC“)) 

{ 

forccLjalert(l,  '[0][Cannot  file  MENU. RSC  fiie(Exiting  ...][0K]*] 

exit(l) ; 

exlt(l); 

> 


get  address  of  menu  */ 

rsrc.jgaddr(0,  MRINMENU^  &mentLjaddr) ; 

display  menu  bar 

menuJba  r ( menuL^ddr  • TRUE ) ; 


wait  for  a message  indicating  a menu  selection 

for(;;)  continue  loop  until  quit 

{ 

eunt^esag ( msg-buf ) ; 

if  (m8gJ9uf[0]  !=  MMJ5ELECTED) not  a menu  message 
continue;  then  ignore 

if  (msgJbuf[4]  ==  QUIT) 

break;  exit  loop  */ 

suitch(msg_buf (4) ) find  object  index 

{ 

case  SRMPLEl:  ring  bell 

Dosound(ding-jdong) ; 
break; 
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Listing  10-2  (continued) 

case  SflMPLE2:  <”•  change  Item  1 state 

If  (meniLjBddr[SflMPLEl].ob_state  ==  DlSfiBLED) 

{ 

menLL_addr[SRMPLEl]  .ob-state  = NORMftL; 
s t rcpy  ( menuLjaddr  [ S AMPLE2  ] . ob^pec « 

" Disable  Door  Beil”); 

> 

else 

{ 

menu^ddr[SRMPLEl]  .ab^tate  = DISRBLEO; 
s trcpy  ( cneniLjaddr  [ SRHPLE2  ] . ob-jspec , 

” Enable  Door  Bell”); 

> 

break; 

case  SAMPLES:  check  or  uncheck  item 

if  (menuuaddr[ SAMPLES ].otLJ5tate  ==  CHECKED) 

{ 

meniLjaddr  [SAMPLES]  .ob^tate  = NORMAL; 
strcpy(fflenu-jaddr[SAMPLE3]  .obuspec, 

* Check  item”); 

) 

else 

{ 

menLLjaddr[SAMPLE3]  .ob^tate  - CHECKED; 

8 1 rcpy  ( menLLjaddr  [ SAMPLES  ] . ob^pec , 

” Uncheck  item”); 

> 

break; 

case  INFO:  display  program  Info 

da-dlalog(INraBOX); 
break; 

default: 

break; 

> 

reset  title  state 

menuLjaddr[msgJbuf  [S]  ] .ab^tate  = NORMAL; 
mBnuJ3ar(mBnu_addr,  TRUE); 

) end  infinite  loop 

Program  Clean-up  and  Exit 


Wait  for  keyboard  before  exiting  program 
r8rc_freo( ) ; 

u-cl8uuk(screen_(jhandle) ; close  workstation 

appl^xltO;  end  program 
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After  displaying  the  new  menu  bar,  MENUl  enters  an  Infinite  loop. 
FYom  this  point  on,  etll  program  flow  Is  controlled  by  events.  When  an 
event  occurs,  the  program  responds  with  the  appropriate  action  and 
waits  for  the  next  event.  Oifly  when  an  event  Indicating  an  exit 
condition  occurs  (such  as  selecting  the  Quit  option  from  the  menu) 
does  the  program  exit  this  Infinite  loop. 

The  first  function  call  within  the  loop  Is  a call  to  evnt-mesag(  ]. 
When  the  program  reaches  this  statement  during  execution.  It  waits 
until  any  message  event  occurs.  Any  other  type  of  event  (such  as  a 
button  pressed  down  or  a mouse  movement)  is  Ignored  because  the 
program  is  only  waiting  for  a message  to  be  received.  When  a message 
is  received,  the  message  buffer  is  filled  and  the  program  continues. 
In  program  MENUl,  if  the  message  Is  not  a menu  selection  message 
(that  Is,  msg-bnilO]  is  not  equal  to  MN-SELECTED),  the  program 
waits  for  another  message  event 

If  a menu-selected  message  Is  received,  element  4 of  the  message 
buffer  array  is  checked  to  see  which  menu  item  is  selected.  If  the 
menu  item  Quit  is  selected,  the  program  breaks  out  of  the  loop  and 
exits  to  the  desktop.  Otherwise,  a switch  statement  on  this  message 
array  element  selects  the  appropriate  action.  If  the  selection  is  item 
SAMPLE  1 (Door  Bell)  the  diDroundf ) function  gives  the  common  two- 
tone  door  bell  sound. 

If  the  item  is  SAMPLE2  (Disable  Door  Bell),  the  program  checks  the 
current  state  of  the  Door  Bell  entry.  If  the  door  bell  Is  currently 
disabled,  it  is  enabled  and  item  SAMPLE2  is  set  to  read  “Disable  Door 
Bell”  so  that  it  can  be  disetbled  the  next  time  through.  If  the  door  bell 
is  currently  enabled,  it  is  disabled  and  item  SAMPLE2  is  set  to  read 
“Enable  Door  BeU.” 

In  case  SAMPLERS,  a similar  toggle  situation  occurs.  If  the  item  is 
currently  checked,  the  item  is  unchecked.  If  the  item  is  currentfy 
imchecked,  the  item  is  checked.  The  text  of  the  selection  is  changed 
according^. 

In  case  INFO,  the  user  is  requesting  information  about  the  menu 
program.  Function  do_dlalog( ) in  the  application  functions  section 
of  MENUl  is  called  with  parameter  INFOBOX.  This  function  is  simpty 
a generalized  version  of  the  get_info()  function  used  in  program 
FORM. 

If  the  item  selected  does  not  match  any  of  the  cases,  the  default 
case  ignores  it  The  last  two  statements  in  the  loop  reset  the  title  of 
the  selected  menu  item.  When  a menu  item  is  selected,  the  AES 
removes  the  drop-down  menu  from  the  screen  £uid  leaves  the  menu 
title  in  its  selected  state  (that  is,  reverse  colors).  For  example,  if  }rau 
touch  the  File  menu  with  the  mouse  at  the  desktop,  the  title  “File”  is 
placed  in  a selected  mode  and  stays  that  way  until  the  operation  has 
been  completed.  When  the  AE)S  reports  the  message  to  your  appllca- 
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tlon,  the  title  is  already  In  its  selected  state.  When  your  program  has 
completed  the  selected  operation,  It  must  reset  the  menu  title  state 
back  to  the  normal  state.  When  the  menu  object  state  is  changed,  the 
menu  bar  must  be  redisplayed  to  show  the  title  In  its  normal  state. 
Element  3 in  the  message  array  contains  the  Index  to  the  title  of  the 
menu  Item  selected. 

MENUl  does  not  wait  for  any  keyboard  events  so  nothing  happens 
when  kQTS  are  pressed.  Your  program  must  handle  the  special 
shortcut  key  codes  set  up  In  the  resource  file  such  as  the  Control-A 
to  get  program  Information  and  Control-Q  to  quit  Program  MENU2 
adds  this  feature  to  MENUl.  Look  through  MENUl  before  continuing. 
Make  sure  that  you  understand  the  concept  of  receiving  messages 
and  how  the  elements  of  the  message  array  are  used.  Then  continue 
to  the  next  program. 


Program  MENU2 

Program  MENU2  Is  an  enhanced  version  of  MENUl.  MENU2  even 
uses  the  same  resource  file  as  MENUl.  MENU2,  however,  handles 
more  events.  Specifically,  MENU2  handles  both  message  and  keyboard 
events. 

In  function  main( ) In  MENU2  (see  Listing  10-3),  the  Initialization 
and  cleanup  are  the  same  as  In  MENUl.  The  primary  enhancement 
over  MENUl  Is  that  the  control  loop  for  event  processing  has  been 
moved  out  of  main()  and  into  Its  own  function  called  controlf). 
Function  control( ) Is  used  throughout  the  rest  of  this  book. 

Listing  10-3  Program  H^ni2 

MENUS. C Menu  demonstration  program  (version  2) 

This  program  shouts  the  use  of  menus  in  an  appiication 
uith  muitipie  euents. 


System  Header  Fiies  & Constants 


Itinciude 

<8tdio«h> 

Standard  10 

t)  include 

<osbind.h> 

GEMDOS  routines 

dinciude 

<gsmdefs.h> 

GEM  RES 

ttinciude 

<obdefs.h> 

GEM  constants 

ttdef  ins 

FPLSE  0 

ttdefine 

TRUE  ! FALSE 
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Listing  10-3  (continued) 

GEM  Rppllcation  Overhead 


Declare  global  arrays  for  VOI. 
typedef  Int  UORD;  UORO  Is  16  bits 

WORD  contrl[12],  VOI  control  array 

lntout[128]«  intin[12B],  VDI  input  arrays 

ptsln[128],  ptsout[128];  VDI  output  arrays  */ 


screen— vhandle. 

/* 

sc  reen-phand 1 e , 

✓» 

screen— rez. 

✓» 

color^creen. 

/* 

x-max. 

/* 

y-max; 

/* 

virtual  screen  uorkstation 
physical  screen  uorkstation 
screen  resolution  0,1,  or  2 
flag  If  color  monitor 
max  X screen  coord 
max  y screen  coord 


Rppllcation  Specific  Data 


ttinclude  *menu.h* 
lldeflne  QUIT_KEY  0x1011 
Ddefine  INFO-KEY  0xle01 

char  ding^ong[]  = { 

0,  239,  1,  0,  7,  62,  8,  8, 
0,  63,  1,  1,  130,  40,  7,  6 

>; 


control -0  to  quit  */ 
control -R  for  about  Info 

array  for  Dosound 
130,  25, 

I,  8,  0,  255,  0 


GEM-related  Functions 


WORD  open_vuork(phys— handle) 

WORD  phys-handle; 

Function:  This  function  opens  a virtual  uorkstation. 

Input:  phys-handle  = physical  uorkstation  handle 

Output:  Returns  handle  of  uorkstation. 

( 

WORD  uork— in[ll], 

uork^ut[57]  , 

nsuL-handle;  handle  of  uorkstation 

int  i; 

for  (i  = 0;  1 < 10;  1++)  set  for  default  values 

uork— ln(l]  = 1; 

uorl<— in[10]  =2;  use  raster  coords 
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Listing  10-3  (continued) 

neu-handle  = phys_handle;  use  currently  open  ukstatlcn 

u^pnuuk(uorl<_ln,  &neLOiandle«  uork^ut); 
return(nevj-handie) ; 

> 

set-j5cr8en_attr( ) 

Function:  Set  global  values  about  screen. 

Input:  None.  Usee  scrBen_vhandle. 

Output:  Sets  x— max,  y_jnax,  color^creen,  and  8creen_rez. 

{ 

UORO  uorl<.jDut[57J ; 

vq.jBxtnd(screen..vhandle,  0,  uork_out); 
x_max  = uork_out[0]; 

^^ax  = uork_DUt[l]; 

screen_rez  = Getrez();  /»  0 = low,  1 = mpd,  2 = high 

color^creen  = (screen_rez  < 2);  mono  2,  color  0 or  1 

> 


Pppllcation  Functions 


do.jdlalog(box.index) 

UORD  box^lndex; 

Function:  Display  a dialog  box. 

Input:  box^jaddr  = index  of  dialog  box 

Output:  Returns  index  of  object  used  for  exit. 

{ 

UORD  xbox,  ybox,  hbox,  ubox; 

UORO  smallx,  smally,  smallu,  smallh; 

UORO  exit^bject; 

OBJECT  »box-addr; 

get  address  of  box  *>' 

rsrc— gaddr(0,  box_J.ndex,  &box_addr); 

gat  size  and  location  of  a box  centered  on  screen  *y 
fornuxenter(box.jaddr,  &xbox,  &ybox,  &ubox,  &hbox); 
smallx  = xbox  + (ubox  ^ 2)i 

smally  = ybox  + (hbox  2);  ^ 

smallu  = 0; 
smallh  =0; 

y*  reserve  area  on  screen  for  box  display 
f o rriLjJ  i a 1 ( FMD-STPRT , 
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Listing  10-3  (continued) 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

draw  an  expanding  box 
fornuriial(FMD_JBRDW, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

drau  dialog  box 

obJc^rau(box^ddr,  0,  10,  xbox,  ybox,  ubox,  hbox); 

handle  dialog  Input 

exlt_obj0ct  = foroLjdo(box-jaddr,  0); 

drau  a shrinking  box 
form-dial  (FWD^HRINK, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

/*  reserve  area  on  screen  for  box  display 
forftLjilal  (FMD-FINISH, 

smallx,  smally,  smallu,  smallh, 
xbox,  ybox,  ubox,  hbox); 

reset  exit  object  state  to  unselected 
box-jaddr[exlt_objGct].ob_state  = N0R{1RL; 

return  ( ex  1 t^bject ) ; 

) 

control ( ) 

Function:  flastar  control  function. 

Input:  None.  Program  Initialization  must  be  done  before 

entering  this  function. 

Output:  None.  Returns  for  normal  program  termination. 

{ 

OBJECT  *menLLjaddr;  address  for  menu 

WORD  mevx,  msvy,  evnt_multl  parameters 

mevbut, 
keystate, 
ksycode, 
mbreturn, 

msg_buf[6);  message  buffer 

WORD  event,  evnt-multl  result  */ 

menu— index;  keyboard  menu  title  selected 

get  address  of  menu 

rsrc.jgaddr(0,  KflINMENU,  &menu-addr); 
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Listing  10-3  (continned) 

display  menu  bar 

msnuUbartmentL^ddr,  TRUE); 

y*  uait  for  a message  Indicating  a menu  selection 
for(;;)  continue  loop  until  quit 

{ 

euent  = es/nt_muiti(  (MULKEVBO  | Mm*IESRG), 


0, 

U mouse  clicks 

0, 

/* 

mouse  buttons  of  interest 

0» 

/* 

button  state 

0. 

first  rectangle  flags 

0,  0, 

x,y  of  1st  rectangle  *y 

0,  0, 

height,  uidht  of  1st  rect 

0, 

/* 

second  rectand  flags 

0,  0, 

/* 

x,y  of  2nd  rect 

0,  0. 

u,h  of  2nd  rect 

msg_buf , 

message  buffer 

0,  0, 

iou,  high  uords  for  timer 

&meux,  &meuy. 

x,y  of  mouse  ev/ent 

&mevbut. 

button  state  at  event 

&keysta te. 

status  of  keyboard  at  event 

&keycode. 

keyboard  code  for  key  pressed 

&mbreturn) ; 

tt  times  mouse  key  enter  state 

if  (euent  & nU_MESRG) 

{ 

if  (msgjbuf[0]  !=  MNJ5ELECTED)  not  a menu  message 

continue;  then  ignore 

if  (msg_buf[4]  ==  QUIT) 

break;  exit  loop 

sui tch(msgj3uf [4] ) find  object  index 

{ 

case  5RMPLE1:  »"ing  bell 

Dosound  ( d i ng^ong ) ; 
break; 

case  5RMPLE2:  change  item  1 state 

if  (menu-addr[SRhPLEl].ob_state  ==  DISRBLEO) 

< 

msnu-^enabie(menuL^ddr,  SRhPLEl,  1); 
msnu_text(menu_addr,  SRKPLE2, 

* Disable  Door  Bell*); 

> 

else 

< 

menuL^ienable(menu_addr , SRMPLEl,  0); 
menLL.text(menLL^ddr«  SRMPLE2, 

* Enable  Door  Bell*); 

> 

break: 
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Listing  10-3  (continned) 

case  SRMPLE3:  check  or  uncheck  Item 

If  (menuLjaddr[ SAMPLES ].ob-JBtate  ==  CHECKED) 

{ 

mBnu_icheck(menuuaddr,  SAMPLES,  0); 
menu-text (monu-jaddr,  SAMPLES,  " Check  item’); 

} 

else 

{ 

flienu-i check (menu-jaddr,  SAMPLES,  1); 

menu— text (menu-addr,  SAMPLES,  ” Uncheck  Item*); 

) 

break; 

case  INFO:  display  program  info 

do^iaiog(INFOBOX); 
break; 


default: 

break; 

) 

reset  title  state 

menu_tnormal(menuLjaddr,  msgjbuf[3],  1); 

) end  message  handler 

if  (event  & MLLKEYBD) 

< 

If  (keycode  ==  QUIT-KEY) 

{ 

menu-index  - FILE; 

menu— tnormai(menu_addr,  menu-lndex,  0); 
break; 

> 


8uitch( keycode) 

case  INFDJ<EY: 

menu— index  = DESK; 

menu-tnormal(fflenuLjaddr,  menu-lndex,  0); 

do_dlalog(IKFQ60X); 

break; 


default: 

break; 

> 

menu— tnormal(menu-addr,  menu— index,  1); 

} end  keyboard  handler 

} end  infinite  loop 

return; 

) end  function 
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Ustliig  ID'S  (eontliiiied) 

/«*•*««««««««•»•«««««•»»»»»««»««»««««*««««««•«»»««• 

Main  Program 


main( ) 

( 

Int  ap-Jd;  application  Inlt  verify 

MDRD  gr^char,  grJichar,  values  for  VDI  handle 

gr^box,  gr_hbox; 

Initialize  GEM  Recess 


ap-ld  = appl_inlt();  Initialize  RES  routines  *>' 

if  (ap— id  < 0)  no  calls  can  be  made  to  RES 

{ use  GEMDOS  *y 

Cconus('***>  Initialization  Error.  <***Sn"); 

Cconus( 'Press  any  key  to  continue. ^n' ] ; 

Craucin(); 

exit(-l);  set  exit  value  to  shou  error 

> 


8creen_phandle  = Get  handle  for  screen 

graf^andle(&gr_uchar,  &grjichar,  &gr_ubox,  &grJibox); 
8creen_vhandle  = operLJVuork(8creerL4}handle) ; 
setter een^ ttr( ) ; Get  screen  attributes 

Rpplication  Specific  Routines 

««  ««  »4H(  ««««««  «««««««««««««««)(«)()(««)()(«««  KKIHt «««/ 


if  ( !rsrc_load(*l1ENU.RSC")) 

{ 

forRLJilert(l,  '[0] [Cannot  file  hENU.RSC  flle|Exiting  ...][0K]*); 
Bxit(l); 

} 


control ( ] ; 


Program  Clean-up  and  Exit 


Malt  for  keyboard  before  exiting  program 
rsrc— free( ) ; 

vucl8vuk(screen-vhandle) ; close  uorkstation 

appl^xit();  end  program 

} 
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Function  control( ) is  basicalty  the  same  set  of  procedures  used  in 
MENUl.  First  the  address  of  the  menu  is  obtained  and  the  menu  is 
displayed.  Then  an  infinite  loop  is  used  for  event  processing.  The  first 
statement  In  the  loop  is  a call  to  event_muld( ) rather  than 
event-mesgf ).  Function  event-mnltif ) waits  for  a specified  event  or 
combination  of  events.  There  are  button  events,  keyboard  events, 
message  events,  mouse  events,  and  timer  events.  Button  events  indi- 
cate that  one  or  more  of  the  mouse  buttons  have  been  pressed. 
Keyboard  events  indicate  that  a key  on  the  kqix>ard  has  been 
pressed.  Message  events  are  sent  from  the  AES  to  the  application  or 
from  one  application  to  another.  Mouse  events  occur  when  the  mouse 
enters  or  leaves  a particular  area  on  the  screen.  A rectan^e  is  used 
as  a parameter  to  specify  the  sensitive  area.  Timer  events  let  a certain 
amount  of  time  pass  before  an  event  happens. 

It  is  not  possible  to  use  individual  event  functions  when  a program 
must  be  ready  to  accept  any  of  a set  of  events  to  occur.  For  example, 
a program  must  wait  for  a button,  a keypress,  or  a message  event 
These  events  may  occur  in  any  order.  If  the  program  uses  an 
evnt-buttonf ) function  to  wait  for  the  mouse  button,  followed  by  an 
evnt-kqrbd( ) function  to  accept  the  keypress,  and  then  an 
evnt_mesag( ) function,  onfy  one  event  is  accepted  at  a time.  When 
this  program  executes,  it  reaches  the  evnt_button( ) function  and 
waits  for  a mouse  button  to  be  pressed.  Regardless  of  the  number  of 
keypresses  or  messages  that  occur,  program  execution  ceases  until 
a mouse  button  is  pressed.  To  avoid  this  single  event  situation,  a 
program  must  use  the  evnt_multi( ) function. 

The  evnt_malti( ) function  waits  for  any  of  a set  of  events.  By 
specifying  the  types  of  events  to  wait  for.  a program  can  accept  the 
first  event  that  comes  along  and  process  it  Take  a look  at  the 
evnt-miilti( ) call  in  function  controlf).  Note  that  it  has  quite  a 
number  of  parameters:  23  to  be  precise.  The  first  parameter  is  a flag 
indicating  which  types  of  events  to  wait  for  and  accept  The  event 
types  are  defined  as  constants  in  the  GEMDEFSJi  file  (see  Table 
10-3).  Each  event  type  is  associated  with  a different  bit  in  this 


Table  10-3:  Event  Type  for  Function 

evnt_multl(  ) 


Constant  Name 

Value 

Event 

MUJKEYBD 

0X01 

Keyboard 

MUJBUTTON 

0X02 

Mouse  button 

MU-Ml 

0X04 

Mouse  event  1 

MUJM2 

0X08 

Mouse  event  2 

MU-MESAG 

0X10 

Message 

MU-TIMER 

0X20 

Timer 
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parameter.  By  ORlng  the  event  types  together  you  can  wait  for  any 
combination  of  events. 

The  next  parameter  in  the  evnt-imilti( ) function  is  the  number  of 
mouse  dicks  that  cause  a button  event.  The  value  of  this  parameter 
determines  the  number  of  clicks  necessary  to  initiate  the  event  The 
time  interval  allowed  between  the  clicks  is  determined  by  the  control 
panel  accessory.  The  third  parameter  lists  the  mouse  buttons  of 
interest  The  least  significant  bit  (bit  0)  corresponds  to  the  furthest 
left  mouse  button.  The  next  bit  corresponds  to  the  next  button  to  the 
right  and  so  on.  If  a bit  for  a particul^  button  is  not  set  that  button 
is  ignored.  The  fourth  parameter  is  the  button  state.  It  is  constructed 
in  the  same  manner  as  the  previous  parameter.  If  the  bit  is  set  to  0 
for  the  button  state,  the  event  is  looking  for  an  “up”  condition  on  the 
button.  If  the  bit  is  set  to  1.  the  event  looks  for  a “down”  condition 
on  the  button. 

A mouse  event  occurs  when  the  mouse  cursor  enters  or  leaves  a 
specified  area  on  the  screen.  Two  different  areas  may  be  listed, 
corresponding  to  a mouse  event  1 or  a mouse  event  2.  The  fifth 
parameter  of  evnt-malti( ) is  a flag  for  the  first  rectangle.  If  this  value 
is  0,  the  mouse  event  1 is  generated  upon  entry  of  the  mouse  into 
the  rectangle.  If  the  value  is  1,  the  event  occurs  upon  exit  of  the 
rectangle.  The  next  two  parameters  give  the  x and  y values  for  the 
upper  left  comer  of  the  first  rectangle  (in  screen  coordinates).  The 
following  two  parameters  are  the  height  and  width  (also  in  screen 
coordinates)  of  the  first  rectangle.  Tlie  next  five  parameters  are  the 
flag,  the  X and  y coordinates,  and  the  width  and  height  of  the  second 
rectan^e. 

The  next  parameter  in  evnt_multi( ) is  a pointer  to  the  message 
buffer  array.  In  the  case  of  a message  event  this  buffer  is  filled  with 
the  message. 

The  next  two  parameters  contain  the  number  of  milliseconds  to 
wait  for  a timer  event  The  number  of  milliseconds  is  essentially  a 
long  value.  A long  value  can  be  divided  into  two  words:  a high  word 
and  a low  word.  The  first  parameter  listed  for  evnt_multi( ) contains 
the  low  word  value  and  the  second  psirameter  the  high  word  value. 

The  next  two  parameters  hold  the  returned  values  of  the  x and  y 
coordinates  (in  screen  coordinates)  of  the  mouse  when  a mouse  event 
has  occurred.  The  next  parameter  holds  the  button  states  at  the  time 
of  a button  event.  This  value  has  the  same  format  as  the  button-state 
parameter  mentioned  above. 

The  parameter  kejrstate  holds  the  status  of  the  keyboard,  speclfl- 
calty  the  right  shift,  left  shift.  Control,  and  Alternate  k^rs.  These 
correspond  to  bits  0 through  3,  respectively.  The  bits  are  set  to  1 if 
the  particular  key  is  depressed  at  the  time  of  the  event  The  keycode 
variable  returns  the  kQrboard  code  for  the  kqr  pressed  in  a kq^board 
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event  The  kQ^odes  are  listed  in  Appendix  C.  The  Isist  parameter 
holds  a value  returned.  This  value  indicates  the  number  of  times  the 
mouse  button  was  clicked. 

The  evnt_malti()  function  also  returns  a value.  This  value  cor- 
responds to  the  event  that  occurs.  In  program  MENU2,  this  value  is 
stored  in  variable  event. 

When  evnt.jniilti( ) is  called,  the  application  waits  for  the  specified 
events  to  occur.  MENU2  waits  for  a k^oard  event  and  a message 
event  The  message  event  is  needed  because  the  user  can  select  a 
menu  item.  The  keyboard  event  is  used  to  coUect  any  possible 
keyboard  shortcut  commands. 

If  a message  event  occurs,  processing  proceeds  exactly  as  in 
MENUl.  However,  this  program  uses  menu  manager  functions  to  set 
the  text  and  state  of  the  menu  selections;  for  example,  menu_ienable( ) 
is  used  to  enable  a menu  item  and  menu^testf ) is  used  to  set  the 
text  of  an  item.  Function  menu_idieck( ) is  used  in  case  SAMPLES 
is  used  to  set  the  checked  status  of  the  menu  item.  At  the  end  of  the 
switch  statement  the  function  menu-tnonnal( ) is  used  to  reset  the 
menu  title  to  its  normal  state.  Note  that  the  menu  bar  does  not  have 
to  be  redrawn  in  this  case. 

If  a keyboard  event  occurs,  the  program  checks  If  the  Quit  key  is 
selected.  If  not  the  program  checks  if  the  Info  key  is  selected.  E^ven 
though  there  is  onfy  one  condition  to  accept  a switch  statement  is 
used  in  controlf ) to  make  it  a more  generalized  control  function.  In 
a kQrboard  event  that  provides  for  quick  menu  access,  the  menu  title 
is  not  highlighted.  To  remain  consistent  with  the  operation  of  the 
GEM  user  interface,  the  program  should  highlight  the  menu  title  of 
the  item  selected.  Use  menu-tnoimalf ) to  set  the  highll^t  The 
variable  mena_index  keeps  track  of  which  menu  title  index  is  high- 
lighted. When  event  processing  is  completed,  the  menu  title  can  be 
reset  to  its  normal  state 

MENU2  demonstrates  how  to  use  the  evnt-imilti( ) function  as  weU 
as  some  menu  manager  functions.  Work  with  MENU2,  and  add  some 
more  keyboard  shortcuts.  At  this  point  you  are  ready  to  create  a basic 
GEM  application. 


Program  LISTE2R 


Now  that  you  have  created  programs  that  use  forms,  menus,  and 
events,  you  sue  ready  to  write  a small  application  program.  Some  of 
the  points  you  should  look  at  in  program  LISTER  are  the  consistency 
of  the  user  Interface,  the  organization  of  the  control! ) function,  the 
modulauliy  of  design,  and  the  use  of  the  file  selector  function, 
&eLJnpiit(). 
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Program  LISTER  Is  a program  that  displays  the  contents  of  a disk 
file.  Most  programmers  use  two  different  formats  for  the  file  display. 
One  format  simply  lists  the  contents  of  the  file  on  the  screen.  This 
format  is  useful  for  files  that  contain  text  only  (characters  with  ASCII 
values  from  32  through  127).  For  other  types  of  files  such  as  program 
or  resource  files,  this  format  would  be  meaningless  because  the 
display  would  be  a series  of  random  characters.  In  this  case,  the 
second  display  format.  caUed  a dump  format,  is  used.  A dump  of  a file 
consists  of  a sequence  of  lines  divided  into  two  parts.  Each  line 
displays  16  bytes  of  the  file.  On  the  left  side  of  the  line  is  the 
hexadecimal  representation  of  the  byte  values.  On  the  right  side  of 
the  line  is  the  character  (also  called  graphics)  representation  of  each. 

Program  LISTER  allows  the  user  to  display  a file  in  either  format 
To  operate  this  program,  the  user  selects  one  display  format  from  the 
menu.  The  program  displays  the  file  selector  dialog  box  provided  by 
the  fi»el_input( ) function  so  that  the  user  can  choose  the  file  to  be 
dlsplajred.  LISTER  then  displays  the  selected  file  in  the  appropriate 
format  If  the  file  display  spans  across  more  than  one  screen,  the 
program  pauses  and  waits  for  the  user  to  press  a key.  When  the  file 
display  finishes,  the  program  returns  to  the  menu  bar. 

The  resource  file  for  LISTER  is  similar  to  the  resource  file  used  for 
programs  MENUl  and  MENU2.  The  LISTER  resource  file  contains  one 
menu  and  one  dialog  box.  Figure  10-3  shows  the  menu  bar  for 
program  LISTER  The  menu  icon  is  called  MAINMENU.  Create  this 
menu  as  shown  in  the  figure.  Name  the  About  LISTER  selection  in 
the  Desk  menu  desk  object  INFO.  For  the  File  menu,  give  the  title  File 
the  name  FILE,  label  the  Text  Display  selection  TEXTFILE.  label  the 
Dump  File  selection  DUMPFILE.  and  label  the  Quit  selection  QUIT. 

The  dialog  box  for  LISTER  Is  shown  in  Figure  10-4.  This  box  simply 
contains  a brief  Information  statement  about  the  program.  The  box 
is  named  INFOBOX. 


About  LISTER 


Desk  Accessory  1 
Desk  Accessory  2 
Desk  Accessory  3 
Desk  Accessory  4 
Desk  Accessory  5 
Desk  Accessory  6 


File 


T I Text  Display 
D I Duap  File 
Q I Quit 


Figure  10-3  Menu  Bar  MAlNM^<iU  for  Program  LIST^ 
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About  LISTER 


This  program  mill  display  a file  on  the 
screen  in  either  text  format  or  using 
a hexadecimal  dump  format. 


Figure  10-4  Dialog  Box  INFOBOX  for  Program  LISTER 


Program  LISTER  has  a new  GEM  application  overhead  variable  (see 
Listing  10-4).  The  variable  mJhiddc^  initlalfy  set  to  FALSE,  keeps 
track  of  the  current  vislbillly  status  of  the  mouse  cursor.  The  mouse 
cursor  can  be  either  visible  (shown  on  the  screen)  or  Invisible.  To 
change  the  status  of  the  mouse  cursor,  two  new  functions  have  been 
added  to  the  GEM-rdated  functions:  hlde-monsef ) and  show-inoiise( ). 
In  hide-monsef ),  if  m_hiHdi»ii  is  FALSE  (meaning  the  mouse  cursor 
Is  current^  visible),  a call  Is  made  to  the  AES  graf_moase( ) function 
to  hide  the  mouse  cursor  and  m_hidden  is  set  according!^.  Function 
8how_mouse( ) performs  the  opposite  task  to  make  the  mouse  cursor 
visible.  It  Is  possible  to  call  the  gra£-mouse( ) function  directly  to  hide 
and  show  the  mouse  cursor.  However,  the  gralLmoiise( ) function  can 
be  nested.  If  you  make  three  consecutive  calls  to  gra£-monse( ) to 
make  the  mouse  cursor  Invisible,  you  need  three  consecutive  calls  to 
graC-mousef ) to  make  the  mouse  cursor  visible  again.  Ttylng  to  keep 
the  calls  to  gralLmouseO  balanced  can  be  confiislng  in  a large 
program.  To  avoid  this  problem,  the  hmctlons  hlde-monsen  and 
8how_mou8e( ) and  the  globed  variable  m hidden  have  been  added  to 
the  GEM  sections  of  the  program.  If  the  mouse  cursor  Is  already 
hidden,  a call  to  hidCLjiioiisef ) does  nothing.  If  the  mouse  cursor 
Is  already  visible,  a call  to  show-monsef ) does  nothing.  Only  If  the 
mouse  cursor  Is  In  the  opposite  state  do  the  functions  change  the 
vislbillly  state  Further  discussion  of  the  grafLmoasel ) function  Is 
presented  in  Chapter  11. 
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Llstiiig  10-4  Ptogram  LISTER 

LISTER. C File  display  program 

This  program  ulll  display  a disk  file  In  text  or  hexadecimal 
format. 

System  Header  Files  L Constants 


Itlnclude 

<8tdlo.h> 

Standard  ID  *y 

Itlnclude 

<osblnd.h> 

GEMDDS  routines 

Itlnclude 

<gemdefs.h> 

GEM  AES  *y 

Itlnclude 

<obdefs.h> 

y* 

GEM  constants  *y 

Itlnclude 

<errno.h> 

y* 

errno  declaration 

tide  fine 

FALSE  0 

tldeflne 

TRUE  ! FALSE 

The  (legamax  compiler  uas  giving  an  error  uhen  the  FILE 
type  definition  was  used.  To  avoid  this  problem,  the 
FILE  type  was  redefined  as  type  FP.  This  error  occurred 
In  this  program  ONLY. 

»✓ 

typedef  FILE  FP; 

/««««»««««»« ««««««« ««««»«« «««««« ««««««««« 

GEM  Application  Overhead 


y*  Declare  global  arrays  for  VDI.  *y 

typedef  Int  UORO;  y*  I40RD  Is  16  bits  *y 

WORD  contrl[12],  VDI  control  array  *y 

lntout[128],  lntln[12B],  y*  VDI  Input  arrays  *y 
ptsln[12a],  ptsout[128]:  y*  VDI  output  arrays  *y 


WORD  screen-vhandle, 
screeo-phandle, 
8creen_rez, 
color^creen, 
x_jnax, 
y^ax, 

m_hldden  = FALSE; 


y*  virtual  screen  workstation  *y 
y*  physical  screen  workstation  *y 
y*  screen  resolution  0,1,  or  2 *y 
y*  flag  If  color  monitor  *y 
y*  max  x screen  coord  *y 
y*  max  y screen  coord  *y 
y*  mouse  visibility  status  *y 


Application  Specific  Data 


Itlnclude  Mister. h” 

ttdeflne  QUITJ<EY  0x1011  y*  control -0  to  quit  *y 
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Listing  10-4  (continued) 

Itdefine  DUMP-KEV  0x2004  control -D  for  dump  file 

Itdeflne  TEXT-J<EY  0x1414  control -T  for  text  file  »/ 

^define  LINEFEED  0x0a 
ttdefine  ESCAPE  27 
ttdefine  CR  13 

int  max^ilnes  = 23;  number  of  lines  to  print 

before  pausing 

char  def^earch[32]  = default  search  path 

sel^flle[16] , /*  file  selected 

fllQ_name[64] ; full  file  name  to  open 

GEM- related  Functions 

UORD  operLJUUork(physJnandle) 

I40RD  phys^andle; 

Function:  This  function  opens  a virtual  workstation. 

Input:  phys^andle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

< 

UDRD  work^n[ll], 

workout  [57] , 

newJiandle;  handle  of  uorkstation 

Int  i; 

for  (1=0;  1 < 10;  1++)  z'*  set  for  default  values 

work«in[l]  = 1; 

work— In [10]  = 2;  use  raster  coords 

new_handlo  = phys_handle;  use  currently  open  wkstation 

v^pnvwk(worl<— In,  &neui_handle,  workout); 
return(new-handle) ; 

> 

set-jBcreen-^ttr( ) 

/««««««««  «««  ««««««««« 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screeru-vhandle. 

Output:  Sets  x_max,  y_max,  color^creen,  and  screen-rez. 

{ 

tdORD  work— out [57] ; 

vq-jQxtnd(screen-vhandle,  0,  work-out); 
x-max  s workout [0]; 
y-ffiax  = worl<— out[l] ; 
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Listing  10-4  (continued) 

Bcr00n_r02  = G0tr0Z();  0 = lou,  1 = m0d,  2 = high 

color^cr00n  = (scroon— t02  < Z);  mono  2,  color  0 or  1 

> 

hide^ous0( ) 

Function:  nako  mouso  invisiblo  if  currently  visible. 

Input:  None.  Uses  variable  m_hidden. 

Output:  Sets  nUiidden  to  TRUE. 

< 

if  (!m_hidden) 

{ 

gra  f -mouse ( MJDFF , 0x0L ) ; 
m-hldden  = TRUE; 

> 

> 

8hou_mouse( ) 

Function:  flake  mouse  visible  if  currently  invisible. 

Input:  None.  Uses  m_hidden. 

Output:  None.  Sets  rtt-hidden  to  FRLSE. 

{ 

if  (m-hidden) 

{ 

graf-mouse(MLON«  0x0L); 
rrLJiidden  = FfiLSE; 

) 

> 


application  Functions 


do-dialog [ box-index ] 

I40RD  box— index; 

Function:  Display  a dialog  box. 

Input:  box_addr  = index  of  dialog  box 

Output:  Returns  index  of  object  used  for  exit. 

< 

NORD  xbox,  ybox,  hbox,  ubox; 

UORD  smailx«  smally,  smailu«  smallh; 

UORD  exit-object; 

OBJECT  «box-addr; 

get  address  of  box 

rsrc-gaddr(0,  box— index,  &box— addr); 
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Llstliig  1(M  (contiimed) 

get  size  and  location  of  a box  centered  on  screen  */ 
forflucenter(box^ddr,  &xbox,  &gbox,  &ubox,  &hbox); 
smaiix  = xbox  + (ubox  ^2); 
smaiiy  = ybox  + (hbox  ^ 2); 
smaiiu  = 0; 
smailh  = 0; 

reserve  area  on  screen  for  box  display 
forriLjdial  (FMDJ5TART, 

smaiix,  smaiiy,  smallw,  smailh, 
xbox,  ybox,  ubox,  hbox); 

draw  an  expanding  box 
form_dial(FMDJSROW, 

smaiix,  smaiiy,  smaiiu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

/»  draw  dialog  box 

obJc^rau(box^ddr,  0,  10,  xbox,  ybox,  ubox,  hbox); 

y*  handle  dialog  input 

exit_jobJect  = form^o(box^ddr,  0); 

draw  a shrinking  box 
form-dial (FWD-SHRINK, 

smaiix,  smaiiy,  smaiiu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

/»  reserve  area  on  screen  for  box  display 
form-dial (FMD-FINISH, 

smaiix,  smaiiy,  smaiiu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

y*  reset  exit  object  state  to  unseiected  *y 
box-addr[exit.  object). ob  state  = NORMAL; 

re  turn  ( ex  i t^b  J ec  t ) ; 

> 

get«flle( ) 

Function:  Get  a file  name  using  file  selector. 

Input:  None.  Uses  def^sarch[]  and  sei_flie(]. 

Output:  FALSE  if  cancelled,  TRUE  otharuise. 

Sets  default  file  search,  file  selected, 
and  filB-name[]  to  contain  the  full  file  name. 

{ 

UQRD  exit-button; 

char  *temp; 

int  i; 
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Listing  10-4  (continned) 

fsel^nput(def^oarch,  sel.filet  &exlt_button) ; 
If  ( lexlt-button)  cancelled 

return(exltJ3utton] ; 


8trcpy( filename,  def^earch); 

1 s strlen( file-name) ; 
temp  - flle_name  -f*  (1  - 1); 
while  ( (<^temp  !=  '\v) 

&&  (^^ternp  != 

&&  (temp  >s  fllB-jiame) 
temp--; 
temp++; 

strcpy(temp,  eel— file); 
return(exltJ3uttcn) ; 


set  path 

point  to  last  character 
search  for  path  end 
drive  Id 

or  start  of  string 

move  to  next  position 
/«  add  file  name 


FP  *open— f lle(xx) 

Int  xx; 

Function:  Open  file  specified  In  flle-name[]  for  read  only. 
Input:  None.  Uses  flie-nafflet]. 

Output:  Returns  file  descriptor  or  NULL. 

{ 

FP  ^^f Ilexes; 


file  .des  = fopen( file-name,  'br'); 

If  (flle-des  ==  NULL) 

fornuorror(-errno);  errors  are  negative  values 

return( f 1 le-des) ; 

> 

end-page ( ) 

Function:  Handle  end  of  page  condition. 

Input:  None. 

Output:  FRLSE  If  abort  requested, 

TRUE  otherwise. 

< 


Cconws( 'Press  any  key  to  continue  or  ESC  to  abort:  *); 
if  ( (CrawclnO  & 0x7f)  ==  ESCfiPE) 
return(FRLSE); 

Cconout(CR);  return  to  start  of  line 

vuesol (screen— vhandle) ; erase  to  end  of  line 

return(TRUE) ; 

} 

tsxt-dlsplay( ) 

Function:  Display  a file  In  text  format. 
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Input:  None. 

Output:  None. 

< 

Int  llne^um,  It  of  lines  printed 

ln_char,  char  from  file  */ 

1; 

FP  *filB-num;  file  descriptor 

have  user  select  a file  */ 

if  (!get.fiie())  /*  file  selection  canceled 

return; 

open  file  for  reading  */ 
fiiajium  = open_fiie(); 

if  (flle_num  »=  NULL)  error  opening  file 

return; 

initialize  for  reading  */ 
hideL^ouse( ) ; 
u^iruk(8creen.uhandie) ; 
w_curhoma(screerL-vhandle) ; 

ilne^um  = 0; 

while  ((inuchar  = getc(fiie_num) ) EOF] 

{ 

printf  ( ’Jtc" , inuchar); 
if  (in-jchar  ==  LINE-FEED) 

{ next  line 

printf ( "Nr* ) ; insure  at  start  of  new  line 

iine-num+*i>; 

> 

if  (iine-num  ==  (nax_iines) 

{ end  of  page  *>' 

IF  (lend-page())  listing  aborted 

break; 

else 

iine-num  = 0; 

> 

) end  uihlle  loop  */ 

f close ( f iie-num) ; 

CconwsfEND  OF  FILE"]; 

Craucin( ) ; 

u-jci  ruk(  screen-uhandie ) ; 
show-mouse ( ) ; 

> 

dump-display ( ) 

Function:  Display  a file  in  hexadecimal  format. 

Input:  None. 
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Ustmg  10-4  (continned) 

Output:  None. 


< 

int  llne_num, 
count, 
i; 

FP  *fll0-num; 

char  in-jchar[16], 
temp [60] ; 

have  user  select  a file 
if  (Iget-flleO) 
return; 

/»  open  file  for  reading 

file-num  = open^flleO; 
if  (flle-num  ==  NULL) 
return; 


tt  of  lines  printed 
>’*  number  of  chars  read 

file  descriptor 
y*  char  from  file 
y*  temporary  format  string 


y*  file  selection  canceled 


error  opening  file 


initialize  for  reading 
hide-mouse ( ) ; 
v^lrul<(screen-vhandle) ; 
v^urhome ( screen— vhandie) ; 

iins-num  = 0; 

while  ((count  = fread(in_xhar,  sizeof (char) , 16,  flle_num))  !=  0) 

< 

for  [1=0;  i < count;  i++)  format  hexadecimal  area 

sprintf (&temp[  1*3] , ' %02x*,  in^har[l]); 
temp[count*3]  =0;  put  null  at  end  »/ 

printf ( **-60s" , temp);  output  left  justified  */ 

for  (1=0;  1 < count;  i++)  y*  output  character  area  *y 
if  (in-i:har[i]  < ' ' I1  in-char[i]  > '"'•) 

printf (•.");  y*  non-prlntable  char  */ 

else 

printf  ( ■Jtc' , in_jchar(  i] ); 
printf ( *\n’ ) ; y*  next  line  */ 

llne-num++; 

if  (iins-num  ==  max— lines)  y*  end  of  page 

if  ( !end-page()) 

break;  y*  listing  aborted  *y 

else 

iine-num  =0; 

^ y*  end  while  loop  *y 

fciose(fiie-num) ; 

CconwsCENO  OF  FILE-); 

Crawcln( ); 

v^  1 r wk  ( sc  reen— vhand  1 e ) ; 
show-mouse ( ) ; 
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Ustlixg  10^  (contiiined) 


control ( ) 

Tunction:  Master  control  function. 

Input:  None.  Program  Initialization  must  be  done  before 

entering  this  function. 

Output:  None.  Returns  for  normal  program  termination. 

{ 


OBJECT 

UlORD 


UORD 


*mentLjaddr; 

meux,  mevg, 

meubut« 

keystate, 

keycods, 

mbreturn, 

msgJsuf [8] ; 

ev/ent, 

menoUndex; 


address  for  menu 
evnt_multi  parameters 


message  buffer 

eunt_multi  result 

keyboard  menu  title  selected 


get  address  of  menu 

rsrc.jgaddr(0,  MRINMENU,  &menu_jaddr) ; 

y*  display  menu  bar 

menu-J]ar  ( menu_addr , TRUE ) ; 

uait  for  a message  indicating  a menu  selection 
for(;;)  continue  loop  until  quit 

{ 

event  = evnt.jnuitl(  (MULKEVBD  | MLOIESPG), 


0, 

tt  mouse  clicks 

0, 

mouse  buttons  of  interest 

0, 

button  state 

0. 

first  rectangle  flags 

0,  0, 

x,y  of  1st  rectangle 

0,  0, 

/» 

height,  uidht  of  1st  rect 

0, 

/« 

second  rectand  flags 

0,  0, 

/« 

x,y  of  2nd  rect 

0,  0, 

ui,h  of  2nd  rect 

msg_ buf , 

/« 

message  buffer 

0,  0, 

lou,  high  words  for  timer 

&mevx,  &mevy. 

x,y  of  mouse  event 

&mevbut. 

button  state  at  event 

&keystate. 

status  of  keyboard  at  event 

&keycode. 

keyboard  code  for  key  pressed 

&mbreturn); 

n times  mouse  key  enter  state 

if  (event  & MLU1ESR6) 

{ 

if  (msg-Jauf(0]  !=  MNJ5ELECTED) 
continue; 
if  (msg_buf[4]  ==  QUIT) 

break;  exit  loop 


not  a menu  message 
then  ignore 
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Lisdiig  10-4  (continned) 

8ultch(m8gJbuf[4])  find  object  index 

{ 

caee  TEXTFILE:  display  file  as  text 

text^ispiay( ) ; 
menuUaar  ( menuuaddr , FfiLSE ) ; 
break; 

case  DUMPFILE:  display  file  in  dump 

dump^ispiay(  ] ; 
mBnuJbar(menu_addr,  FRLSE); 
break; 

case  INFO:  display  program  info 

dQ_dlalog(INFOBOX); 
break; 

default: 

break; 

> 

/»  reset  title  state 
menu-.tnormal(menuLjaddr,  msgJbuf[3],  1); 
menu-_bar  ( menu_addr , TRUE  ] ; 

} end  message  handler 

if  (event  & MULKEYBD) 

{ 

If  (keycDde  ==  QUIT-KEV) 

< 

memjL-lndox  = FILE; 

menu_tnormal(menu^ddr,  menu_andex,  0); 
break; 

} 


eui tch ( keycode ) 

{ 

case  TEXT-KEY: 

menuL-lndex  = FILE; 

menu— tnormal(mena_addr,  menu— index,  0); 

text-display( ) ; 

menuJbar  ( menuLjaddr , FRLSE ) ; 

break; 

case  DUMP-KEY: 

menu— index  = FILE; 

menu— t norma iCmenu-addr,  menu— index,  0); 
dump^ispiay( ) ; 
menu_bar(menu_addr,  FRLSE) ; 
break; 

default: 

break; 
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Listing  10-4  (continued) 

) 

mQnLL.tnor(Rai(mBnuuaddr,  menu_index,  1); 
m8nLLJ3ar(menuL-addr,  TRUE); 

} y*  end  keyboard  handler 

} /*  end  infinite  ioop 

return; 

) /«  and  function 

Main  Program 


maln( ) 

{ 

int  ap_id;  appiication  init  verify  »>' 

t40R0  gr^char,  gr_hchar,  values  for  VDI  handle 

gr^box*  gr_hbox; 


Initialize  GEM  Recess 


ap_id  = appl^lnltO;  Initialize  AES  routines 

If  (ap— Id  < 0)  /*  no  calls  can  be  made  to  RES 

{ /*  use  GEMDOS  »/ 

Cconws(*»»*>  Initialization  Error.  <***\n*)i 
Cccnus(  "Press  any  key  to  continue- '^n" ) ; 

Craucln( ) ; 

exit(-l);  set  exit  value  to  shout  error 

> 


screerL^shandle  = Got  handle  for  screen 

graf Jnandls(&gr_uchar,  &gr_hchar,  &gr^box,  &gr_hbox); 
BcreerL.vhandle  - operL.vuorl<(screen_phandls) ; 
8Bt-_scr0en_attr( ) ; Get  screen  attributes 


Application  Specific  Routines 

if  ( !rsrc^load( "LISTER. RSC")) 

( 

form_^lert(l,  "[0] [Cannot  file  LISTER. RSC  file|Exiting  •••]  [QK]'); 
sxlt(l); 

> 


control ( ) ; 
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U8tiiigl0-4  (continned) 

/«««  XKIHIKKIHHHIKIHIK  ««««««««»  «««««««« IHHHHHHI 

Program  Clean-up  and  Exit 

/*  Wait  for  keyboard  before  exiting  program 
rsrc^free( ); 

v_cl8Vuk(8crQerL.uhandie);  close  workstation  */ 

appl^xltO;  end  program 

> 


With  regard  to  the  various  overhead  used  by  LISTER,  note  that  the 
LISTER.H  header  file  Is  Included  In  the  application-specific  data 
section  of  the  program.  The  constants  QUIT-KEY,  DUMP-KEY,  euid 
TEXT-KEY  represent  the  keyboard  key  codes  for  the  menu  shortcuts. 
The  kQT  code  values  are  in  Appendix  C.  The  constants  LINE-FEED, 
ESCAPE,  and  CR  represent  the  line  feed,  escape,  and  carriage  return 
characters.  These  characters  are  used  to  format  the  display.  A line 
feed-carriage  return  combination  indicates  the  end  of  a line  in  a file. 

The  ^obal  variable  max-lines  is  set  to  the  number  of  dlspls^r  lines 
per  “page.”  As  shown  In  Listing  10-4,  LISTER  onfy  outputs  the  display 
to  the  screen.  However,  you  can  modify  the  program  to  ou^ut  to  the 
printer  or  another  disk  file.  For  screen  output,  the  number  of  lines 
that  can  be  displayed  before  the  program  must  pause  is  23.  For 
printer  output  the  number  of  lines  printed  before  a new  page  is 
required  is  60  (assuming  an  11-lnch  page  length  at  six  lines  per 
inch).  For  disk  output  there  is  no  limit  on  the  number  of  lines.  If 
these  alternate  output  destinations  are  Implemented,  the  maximum 
line  value  must  be  able  to  change.  Therefore,  max-lines  is  a ^obal 
variable  rather  than  a preset  constant 

The  last  bit  of  application-specific  data  consists  of  three  character 
arrays  called  def-seardi,  seJ-flle,  and  file-name.  These  arrays  are 
used  in  conjunction  with  the  feeLJiqnit( ) function.  The  defLsearch 
string  contains  the  default  search  path  to  use  when  fi9el-input( ) is 
initiated.  The  sel_file  string  contains  the  default  file  name  to  be 
selected.  When  fiseLJnpnt( ) returns  to  the  calling  program,  sel-flle 
contains  the  name  of  the  selected  file.  To  open  a file,  the  complete 
path-  and  filename  must  be  used.  However,  the  pathname  is  con- 
tained in  Hrf  KMrrfi  and  the  filename  is  held  in  seLfile.  These  two 
strings  are  combined  into  a single  filename  in  string  fileLjiame. 

Function  main()  is  the  same  as  in  the  last  three  programs.  The 
resource  file  load^  for  this  program  is  LISTERRSC.  In  the  control( ) 
function,  evnt-mnlti( ) waits  for  a kqrboard  or  message  event  Elach 
fype  of  event  has  its  own  section  for  processing.  In  the  message  event 
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section,  only  a menu  selection  is  processed.  Otherwise  the  message  is 
ignored.  A QUIT  selection  causes  an  exit  from  the  infinite  loop. 
Selection  of  the  TEXTFILE  dii^lay  calls  fimctlon  text-displi^ ) and 
then  turns  the  menu  bar  off.  The  menu  bar  is  turned  off  because  the 
display  function  uses  the  entire  screen,  including  the  area  for  the 
menu  bar.  When  the  display  is  completed,  the  entire  screen  is  cleared 
and  the  menu  bar  must  be  redispla}red.  To  ensure  that  the  menu  bar 
is  displayed  property,  it  is  turned  off  and  then  turned  back  on.  TTie 
DUMPFTLE  selection  calls  function  domp-dispkqrO  and  turns  the 
menu  bar  off.  Case  INFO  is  a request  for  more  Information,  so 
do-dialog( ) is  called  with  the  index  to  INFOBOX. 

The  keyboard  event  handler  works  similarly  to  the  message  event 
handler.  Note  that  the  keyboard  event  handler  must  explicitly  change 
the  menu  title  to  its  Inverse  state  before  processing. 

Functions  tezt_display( ) £md  dump_di^lay( ) follow  the  seune 
basic  program  flow.  They  get  a selected  filename  from  the  user 
through  function  get_file( ).  Next  the  selected  file  is  opened  in  func- 
tion open_file( ).  Once  the  file  is  open,  the  display  process  can  begin. 
Functions  test-dlsplayf ) and  danqr-displayf ) then  hide  the  mouse, 
clear  the  screen,  and  perform  their  display  functions  in  the  ap- 
propriate format.  When  the  end  of  the  file  is  encoimtered,  the  file  is 
closed,  the  screen  is  cleared  again,  emd  the  mouse  is  turned  back  on. 
The  two  routines  both  pause  the  output  display  when  the  screen  has 
been  filled.  Ihe  function  emL^iageC ) handles  this  condition. 

The  get-file()  routine  uses  the  file  selector  meinager.  A call  to 
fiseLinputf ) provides  the  user  with  a dialog  box  that  allows  the  user 
to  select  a disk  drive,  a directoiy,  and  a particular  file.  The  first 
parameter  in  fisel_input()  is  the  default  search  path.  The  second 
parameter  is  the  default  file  to  be  selected.  The  default  file  and  default 
directoiy  are  initialized  in  variables  def_search  and  sd-file  already 
mentioned  above.  Upon  returning,  fi«sLJnpiit( ) sets  all  three  of  its 
parameters.  The  parameter  esitL.battoii  is  set  to  a value  indicating 
that  the  Elxit  button  is  selected.  If  esit_button  is  set  to  0,  the  “Cancel” 
button  is  selected.  Otherwise  exit-button  is  set  to  1 to  Indicate  the 
OK  button.  The  default  search  string  and  the  default  file  selection 
string  are  set  to  the  new  values  entered  by  the  user. 

After  the  file  has  been  selected,  a full  filename  specification  needs 
to  be  created.  Function  get-file( ) combines  the  returned  search  direc- 
tory and  selected  filename  so  that  a complete  file  and  path  descrip- 
tion is  set  The  search  path-  and  filename  are  combined  into  variable 
file-name  so  that  a full  file  specification  is  available  to  the  rest  of  the 
program. 

Function  open_file()  uses  fopenf)  to  open  the  file.  If  an  error 
occurs,  open_file()  caUs  the  AES  function  fonn-enorO.  Function 
fonn_error( ) displays  an  error  box.  The  parameter  to  fonn-eixor( ) 
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determines  the  error  message  displayed.  This  parameter  must  be  a 
positive  value.  However,  the  variable  ermo.  the  global  error  variable 
used  the  C compiler  (see  file  ERRNO.H),  contains  the  error  number 
as  a negative  value.  Therefore,  the  sign  of  the  parameter  to 
foim_eiTOT( ) is  inverted. 

Program  LISTER  has  been  written  so  that  you  can  see  how  the  file 
selector  dialog  box  works  and  how  an  Explication  is  written  to  utilize 
events  and  the  menu  bar.  As  Indicated  earlier,  you  may  want  to  add 
an  option  to  have  the  output  printed  on  the  printer.  You  can  imple- 
ment this  as  a toggled  menu  selection  using  the  CHECKED  state  to 
turn  on  and  off  the  printer  output  Other  menu  sdections  can  also 
be  added  to  set  page  length  and  page  width  of  the  printer  output 
Since  program  LISTER  is  relative^'  modular,  you  should  be  able  to 
install  these  enhancements  with  little  difilculty. 


CHAPTER  ELEVEN 

Building  a Better 
Mouse  Trap 


Dialog  boxes,  menus,  and  the  file  sdector  have  all  been  handled  by 
AES  routines.  This  chapter  provides  a basic  understanding  of  how 
the  AES  handles  these  user  interactions.  With  the  routines  in  the 
AES  graphics  library,  you  can  emulate  many  of  the  interface  features 
provided  by  GEM.  For  example,  you  can  make  slide  bars,  buttons,  and 
dragging  and  sizing  boxes.  From  this  basis,  you  can  then  create  your 
own  Interface  features  to  customize  your  programs.  To  provide  a 
graphics-based  user  interface,  a program  must  have  gr£^hics  routines 
and  mouse  access,  both  of  which  are  provided  by  the  graphics  library. 

Most  of  the  routines  in  the  graphics  library  control  boxes  in  the 
GEM  environment  A box  is  simpty  a rectangular  image  drawn  on  the 
screen.  An  outlined  box  is  a lighter  rectangular  image  drawn  in 
half-intensity.  The  outline  is  used  to  indicate  that  some  change  can 
now  occur  on  the  selected  box.  For  example,  when  you  resize  a 
window,  Ein  outlined  image  of  the  window  is  used  to  show  the  new 
window  size.  When  you  move  a ^window,  the  outline  of  the  window 
shows  the  new  window  location.  When  using  the  AE^,  a rectangular 
area  is  identified  by  the  coordinates  of  its  upper  left  comer,  its  width, 
and  its  height  All  AEIS  routines  refer  to  rectangles  in  these  terms. 
This  is  different  from  the  VDI,  which  uses  the  coordinates  of  the 
upper  left  and  lower  right  comers.  This  difference  becomes  important 
when  you  are  programming  with  both  the  AEIS  and  the  VDI. 

There  are  ten  graphics  routines  in  the  graphics  manager: 
grafLdragbozf ),  graf_growboz( ),  graf-handle( ),  gral_mboz( ), 
graf-mhfrtate( ),  gca£_moase( ),  gra£_iiibbefboz( ),  gtnf-ahrlnkbozf ). 
gra£_slideboz( ),  and  grafLwatchbozf ).  Brief  descriptions  of  each  are 
provided  below;  for  complete  operational  descriptions,  see  Appendix  A. 
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The  gia£-dra^boK( ) function  lets  a user  drag  an  outline  within  an 
application-defined  boundaiy  rectangle.  For  example,  when  you  want 
to  move  an  object  in  the  resource  editor  program,  you  simply  press 
the  mouse  button  while  on  that  object  A hand  appears  and  you  can 
drag  the  outline  around.  When  you  release  the  button,  the  object 
moves  to  the  position  of  the  outline.  Function  gcaL.diagboz( ) controls 
the  process  of  moving  the  outline  under  mouse  control.  When  the 
user  releases  the  mouse  button,  the  ftmctlon  returns  the  x and  y 
coordinates  on  the  screen  of  the  upper  left  comer  of  the  box. 

The  grafLgrowbozf ) ftmctlon  draws  an  expanding  box  outline.  This 
is  the  function  used  by  f6rm-dlal( ) to  show  the  expanding  box.  Hie 
function  is  given  the  size  and  position  of  the  small  box  outline.  This 
outline  is  drawn  and  then  expands  to  the  size  and  position  of  the 
large  outline. 

Function  graiLhandlet ) has  been  used  in  all  programs  presented 
thus  far  and  will  continue  to  be  used.  This  routine  returns  the  handle 
to  the  current  open  screen  workstation  being  used  by  GEM. 

The  graf-mb<«()  function  shows  a box  outline  moving  from  one 
position  to  another.  This  function  takes  the  initial  size  and  location 
of  the  rectan^e  and  the  final  location  of  the  rectangle  The  size  of  the 
box  is  not  changed  at  all.  The  GEM  documentation  lists  the  name  of 
this  function  as  gra£-moveboz( ).  The  Megamax  compiler  has  imple- 
mented this  function  with  the  name  grafLndM»c().  Check  your  com- 
piler manual  to  see  vdiich  name  is  used  for  this  function. 

Function  graf-mkatatef ) returns  the  current  mouse  position,  the 
state  of  the  mouse  buttons,  and  the  state  of  the  keyboard.  Button  and 
keyboard  state  values  are  returned  in  the  same  bit  format  as  for  the 
evnt_multi( ) function  described  in  Chapter  10. 

The  gniLjiiousef ) function  lets  the  application  change  the  mouse 
form  to  one  of  a predefined  set  of  forms  or  to  an  application-defined 
form.  This  function  also  allows  the  application  to  hide  and  show  the 
mouse,  as  done  in  program  LISTER  The  header  file  gemdefis.h 
defines  the  constant  names  for  the  different  mouse  forms  (see  Table 
1-1). 

The  graf_mouse( ) function  has  two  parameters.  The  first  parameter 
is  one  of  the  constant  values  identifying  the  mouse  form  to  use.  If  the 
constant  used  is  USERJDEF,  the  second  parameter  is  used  as  a 
pointer  to  a mouse  form  definition  block  defined  as  structure  MFORM 
in  file  gemde&.li  (see  Figure  11-1).  The  MFORM  structure  has 
fields  mf-mask  and  mfLdata  which  are  16-by-16  bit  arrays.  The 
mf-mask  array  contains  the  mask  bit  map  of  the  mouse  image.  The 
mfLdata  array  defines  the  data  bit  map  of  the  Image.  The  mask  and 
data  bit  maps  are  used  to  move  the  mouse  around  the  screen  in  the 
same  way  the  ball  moves  in  program  BOUNCE.  The  fields  mf-xhot 
and  mfLyliot  determine  the  hot  spot  of  the  mouse.  The  hot  spot  is 
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Table  11-1:  Moose  Ponn  Constant  Names 


Constant  Name  Value Form  Image 


ARROW  0 

TTXT-CRSR  1 

HOURGLASS  2 

POINT_HAND  3 

FLAT-HAND  4 

THIN-CROSS  5 

THICKjCROSS  6 

OUTLN-CROSS  7 

USER-DEF  255 

M-OFF  256 

M-ON  257 


Arrow 

Text  cursor  (vertical  bar) 
Bumble  bee 

Hand  with  pointing  Anger 
Open  hand 
Thin  crosshair 
Thick  crosshair 
Outlined  crosshair 
User-deAned  Image 
Turn  oA*  mouse  cursor 
Turn  on  mouse  cursor 


the  point  on  the  mouse  Image  used  to  locate  the  mouse  on  the  screen. 
For  example,  the  hot  spot  for  the  arrow  Image  would  be  at  the  tip  of 
the  arrow;  the  hot  spot  for  the  cross  hair  would  be  at  the  center  of 
the  cross;  and  the  hot  spot  for  a pointing  hand  would  be  at  the  tip 
of  the  finger.  The  x and  y coordinates  of  the  hot  spot  are  measured 
in  pixels  relative  to  the  upper  left  comer  of  the  image.  The  mC-nplanes 
field  indicates  the  number  of  planes  in  the  bit  map.  The  mC-^  and 
mC-bg  fields  sp>ecify  the  color  index  for  the  foreground  and  back- 
ground colors  respectively. 

typedaf  struct  mfstr  { 


140RD 

mf_xhot; 

mRD 

mf_yhot; 

I40RD 

mf_yhot; 

UORD 

mf_np lanes; 

UORD 

UORD 

mf_bg; 

UORD 

mf^asl<[16] ; 

UORD 
} MFORM; 

mf^ate(16] ; 

Flgnie  11-1  Hie  MFORM  Stnictuie 

The  gcafLmbbexboxf ) function  draws  a rectangle  that  can  expand 
and  contract  with  mouse  movement  This  is  the  routine  that  controls 
the  outline  when  a window  is  resized.  The  upper  left  comer  of  the 
outline  rectangle  remains  fixed,  whfie  the  lower  comer  moves  to 
determine  the  new  size  of  the  window. 

The  graf-8hrinkboz( ) performs  the  opposite  function  of 
gta£-growboz( ).  It  draws  a shrinking  outline. 
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Function  grafLdideboxC ) keeps  a sliding  box  object  within  its 
parent  box.  This  is  the  routine  used  for  the  slide  bars.  The 
gra£.slideboz( ) function  requires  that  the  two  boxes  be  objects  and 
that  the  parent  box  contain  the  sliding  box.  Function  grafLslidebox( ) 
makes  sure  that  the  sliding  box  stays  within  the  boundaries  of  the 
parent  box. 

The  last  graphics  library  routine.  gra£-watchbox( ),  watches  a rec- 
tangle while  the  user  presses  a button  on  the  mouse.  For  example, 
move  the  mouse  to  the  close  box  of  a window.  Press  the  left  mouse 
button,  and  hold  it  down.  As  long  as  the  button  remains  depressed 
and  the  mouse  stays  within  the  close  box.  the  close  box  will  be  shown 
as  selected.  Now  while  holding  the  mouse  button  down,  move  the 
mouse  outside  the  close  box.  As  soon  as  the  mouse  exits  the  close 
box.  the  close  box  returns  to  its  normal  state.  Function  graf-watchbox( ) 
is  used  to  perform  this  action.  When  the  mouse  button  is  releetsed. 
grafLwatdibosf ) returns  a value  indicating  whether  the  mouse  was 
inside  or  outside  the  box  watched. 


Program  MOUSE 

Program  MOUSE  demonstrates  the  graphics  library  functions,  mouse 
events,  and  the  use  of  a free-type  tree  in  the  resource  file.  The 
graphics  library  routines  can  be  divided  into  five  different  categories. 
The  first  category  deals  with  box  movement  such  as  growing,  shrink- 
ing. moving,  and  sizing.  The  next  category  hemdles  the  sliding  boxes. 
The  third  category  is  for  the  grafLwatchbozf ) routine.  The  fourth 
category  includes  mouse-handling  functions.  Finally,  the  fifth  category 
is  for  the  gra£.handle( ) routine.  Each  of  the  first  fovir  categories  is 
demonstrated  in  a different  area  on  the  screen  in  program  MOUSE. 
When  the  program  is  running,  the  user  sees  a box  divided  into  four 
boxes  (see  Figure  1 1-2).  The  upper  left  area  demonstrates  moving  and 
sizing  boxes.  The  upper  right  area  is  for  sliding  boxes.  The  lower  left 
area  has  a box  that  is  watched.  The  lower  right  area  shows  the  results 
of  a mouse  event 

The  Resource  FUe  for  Program  MOUSE 

The  easiest  way  to  create  a screen  layout  is  through  the  resource  file. 
Therefore,  the  first  thing  to  do  is  to  create  a resource  file  for  program 
MOUSE.  This  resource  file  contains  a menu  bar  and  a free  tree.  The 
menu  bar.  named  MAINMENU.  is  the  default  menu  bar.  In  other 
words,  it  includes  the  Desk  and  File  menus  only.  Under  the  Desk 
menu,  the  first  entry  should  be  changed  to  read  “MOUSE  Tester”  and 
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neuned  INFXD.  The  File  menu  has  only  the  Quit  selection,  which  should 
be  named  QUIT.  Although  there  Is  no  Information  dialog  box  for  this 
program,  the  INFO  menu  selection  must  be  named  because  if  it  is 
selected  by  the  user,  the  program  must  be  able  to  handle  the  selection 
(even  if  nothing  is  done). 

The  next  tree  to  create  for  program  MOUSE  is  a free  tree.  A free 
tree  is  used  here  because  a dialog  box  causes  all  objects  to  be 
character-aligned.  This  restriction  is  not  desired  for  MOUSE.  To 
create  a free  tree,  drag  the  free  tree  icon  to  the  woric  area  of  the  main 
window  and  name  it  MAINTREE.  Open  this  free  tree.  You  shoviid  have 
a box  that  is  the  root  object  in  MAINTREE.  Resize  this  box  so  that  it 
fits  within  one-quarter  of  the  screen.  MAINTREE  consists  of  a large 
box  (the  root)  containing  four  smaller  boxes.  To  create  the  four 
smaller  boxes,  drag  a box  from  the  parts  box  to  the  free  tree  bmc  Size 
and  position  this  box  to  correspond  with  the  upper  left  box  shown  in 
Figure  11-2;  the  exact  size  and  position  of  the  first  box  is  not 
important  It  would  be  rather  cumbersome  to  tiy  to  make  three  more 
boxes  exactly  the  same  size  as  the  first  As  a shortcut  simply  copy 
the  first  box.  Place  the  mouse  cursor  over  the  box  you  just  created. 
Hold  down  the  Shift  k^,  and  press  the  mouse  button.  Now  drag  the 
box  to  the  right  so  that  it  is  next  to  the  first  box.  When  the  copy  is 
in  position,  release  the  mouse  button.  If  you  didn’t  position  the  new 
box  exactly  right,  you  can  move  it  again.  The  Shift-Click  combination 
causes  the  resource  editor  program  to  make  a copy  of  the  object  Both 
the  RCS  and  MMRCP  programs  allow  the  user  to  copy  objects  in  this 
manner.  Repeat  this  procedure  for  the  two  lower  boxes.  When  you 
have  the  four  boxes,  name  the  upper  left  box  BOXO,  the  upper  right 
box  BOXl,  the  lower  left  box  BOX2,  and  the  lower  right  box  BOX3. 
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BOXO  contains  a box  named  FLEXBOX  Inside  FLEXBOX  eupe  two 
STRING  objects  and  a smaller  box.  The  first  string  says  “Flexible”  and 
is  named  FTEXBOXl.  The  other  string  “Box”  is  named  FLEXBOX2. 
The  small  box  is  named  SIZEBOX.  As  you  might  guess,  the  objects  in 
BOXO  are  going  to  be  used  to  demonstrate  moving  and  sizing  a 
rectangle. 

In  BOXl  are  two  slide  bars.  The  horizontal  large  box  is  named 
HSLIDEIN,  and  the  slider  contained  within  is  named  HSLIDE.  Note 
that  the  slider  Itself  Is  filled  with  a pattern.  The  vertical  slide  bar  is 
named  VSLIDEIN:  its  slider  is  named  VSLIDE.  Mstke  sure  that  the 
sliders  fit  inside  the  slide  bars.  The  slider  object  must  be  a child  of 
its  slide  bar.  The  objects  in  BOXl  are  going  to  be  used  to  demonstrate 
the  gtaLalidebozf ) function. 

BOX2  contains  a button  with  the  text  "WATCH.”  This  button  is 
named  WATCHBOX.  Below  it  is  a STRING  object  with  text  that  says 
“Off.”  This  string  is  named  WATCHTXT. 

BOX3  defines  the  area  used  for  a mouse  event  Inside  BOX3  are 
three  STRING  objects  for  the  text  “Change,”  “Mouse,"  and  “Form,” 
These  strings  do  not  have  any  names. 

The  menu  bar  and  the  free  tree  alone  make  up  this  resource  file. 
Figure  1 1-3  shows  the  object  tree  layout  for  the  free  tree.  Once  you 
have  named  all  the  objects,  save  this  resource  in  file  MOUSE.RSC. 


FigDTe  11-3  MOUSE.RSC  Free  Tree  Layout 


The  Listing/or  Program  MOUSE 

In  the  £^plication-specific  data  section  of  program  MOUSE,  the  first 
statement  Includes  the  MOUSE.H  file.  Variable  tree-addr  holds  the 
address  of  the  free  tree.  The  structure  GRECT  is  the  AES  format  for 
a rectangle.  It  contains  held  g-x,  g-y,  g-w,  and  for  the  X and  y 
coordinates  and  the  width  and  height  of  a rectangle.  The  box  array 
in  program  MOUSE  holds  the  dimensions  of  boxes  BOXO.  BOXl, 
BOX2,  and  BOX3.  This  is  why  the  exact  position  and  size  of  these 
objects  is  not  important  in  the  resource  file.  Program  MOUSE  looks 
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In  the  OBJEX^T  structure  of  these  boxes  and  finds  their  sizes  and 
positions  on  the  screen. 

In  the  GEM-related  function  section,  the  new  routine  load-xe- 
sourcef ) has  been  added.  This  function  is  simply  a generalized  rou- 
tine to  load  a resource  file.  If  3^ou  want  to  provide  for  a more  robust 
error-handling  scheme,  you  can  change  load_resoarce( ) instead  of 
fiddling  with  function  mainf ).  This  separation  of  tasks  holds  to  the 
moduletr  design  philosophy. 

In  function  main( ),  the  program  initialization  and  resource  load  is 
basical]^  the  same  as  in  previous  programs.  The  first  application 
fimctlon  is  InittoHzef  ],  which  initializes  the  global  variables,  the  box 
array,  and  the  tree  address.  Once  the  initialization  is  completed,  the 
program  moves  to  function  contndf ). 

Function  initializef ) first  calls  Ude-mousef ) to  hide  the  mouse 
cursor.  Next  tree_addr  is  set  to  the  address  of  MAINTREE  and  the 
screen  is  cleared.  The  position  of  MAINTREE  is  chemged  to  coor- 
dinates (10,20).  When  the  resource  editor  creates  a tree,  the  root  is 
located  at  (0,0).  If  the  root  is  left  at  this  position,  the  image  would 
conflict  with  the  menu  bar.  Therefore,  the  coordinates  of  the  root  are 
moved  down  past  the  menu  bar.  Since  the  coordinates  of  all  children 
of  the  root  are  placed  with  respect  to  the  root  simpfy  moving  the  root 
coordinates  moves  all  of  its  children  accordingly.  This  is  a rather 
convenient  feature. 

Listing  11-1  Program  MOUSE 

MOUSE. C Mouse  demonstration  program 


This  program  shous  hou  to  use  the  mouse,  event  manager, 
object  library,  and  graphics  library. 


System  Header  Files  & Constants 


ttinciude 

<stdio.h> 

/ft 

Standard  IQ 

tlinciude 

<osbind.h> 

/ft 

GEMDOS  routines 

tt  include 

<gemdefs.h> 

/ft 

GEM  AES  »/ 

ttinclude 

<obdefs.h> 

/ft 

GEM  constants 

Uinclude 

<errno.h> 

/ft 

errno  declaration  */ 

ttdef  ins 

FALSE  0 

ttdaf  ine 

TRUE  ! FALSE 

/ K 4(  « 4H(  » « 41  ilK  K « « « « « « « K ft  41 « 4(  4(  K 4HH(  • 1HH(  ft  « ft  « 4(  ««  ft  « ft  ft  ft  4(  4(  4(  4( 

GEM  Application  Overhead 

ftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftftft/ 
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Listing  11-1  (continued) 

Declare  global  arrays  for  VOI. 
typedef  int  WORD;  WORD  is  16  bits 

WORD  contrl[12],  VDI  control  array 

intout[126],  intin[128],  VDI  input  arrays 
ptsln[126],  ptsout[128];  VDI  output  arrays 

WORD  screen_vhandle,  v/lrtual  screen  uorkstation 

screen_phandle,  physical  screen  workstation 

screon_rez,  screen  resolution  0,1,  or  2 

color— screen,  flag  If  color  monitor 

x_max,  max  x screen  coord 

y^ax,  max  y screen  coord 

m_hldden  = FALSE;  mouse  visibility  status 

Application  Specific  Data 

ttinciude  *mouse.h” 

OBJECT  ^tree^ddr;  address  of  screen  tree  */ 

6RECT  box[4];  4 rectangles  on  screen 

/ « « KKK  iHHHHHHHHIK  « 4HHH(  « « « »)HI  »« 

GEM-related  Functions 

WORD  operL.vuork(phys-handie) 

WORD  phys-handie; 

Function:  This  function  opens  a virtual  uorkstation. 

Input:  phys-handie  = physical  uorkstation  handle 

Output:  Returns  handle  of  uorkstation. 

( 

UDRD  uorl<_ln[ll]. 

uork^ut[57] , 

neu_handie;  handle  of  uorkstation 

int  1; 

for  (i  = 0;  i < 10;  i++)  set  for  default  values 

uork_in[i]  = 1; 

uorl<— in[10]  = 2;  use  raster  coords 

neu-handie  = phys-handie;  use  currently  open  ukstation 

v^pnvuk(uork^n,  &neu-handie,  uork_out); 
re  turn ( new-handi e ) ; 

> 

set-screerLjattr( ) 

/IIIHMHHHHHHHI  »»»«*»»  «K4H( 

Function:  Set  global  values  about  screen. 
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Listing  11-1  (continued) 

Input:  None.  Uses  screerL-vhandle. 

Output:  Sets  x_max,  y^ax,  col  onscreen,  and  screen^ez. 

{ 

UORD  ua  rk^u  t ( 57  ] ; 

vq^xtnd(screen_vhandle,  0,  workout); 
x^ax  = uorl<-jDUt[0] ; 
y_max  = uorl<^ut[l); 

screen_rez  = Getrez();  0 = lou,  1 = med,  2 - high 

color«j5cr0Gn  = (screen—rez  < 2);  mono  2,  color  0 or  1 

) 

hide— mouse ( ) 

Function:  hake  mouse  invisible  if  currently  visible. 

Input:  None.  Uses  variable  nuJiidden. 

Output:  Sets  m_hldden  to  TRUE. 

{ 

if  ( Im-hidden) 

< 

gr a f-mouse  ( (1L0FF , 0x0L ) ; 
m-hidden  = TRUE; 

> 

> 


shou^ouse( ) 

/««««»««««»«««««««»««««««««)(««««««««««««««««««««««« 
Function:  hake  mouse  visible  if  currently  invisible. 
Input:  None.  Uses  ouhidden. 

Output:  None.  Sets  ouhidden  to  FPLSE. 

{ 

if  (ciuJildden) 

{ 

gra  f.jnouse  ( f1_0N , 0x0L ) ; 
nOilddsn  = FftLSE; 

) 

> 

loacL_resource(  rf  i le ) 
char  *rfile; 

Function:  Load  resource  file. 

Input:  rflle  - string  ulth  resource  file  name. 

Output:  Returns  TRUE  if  file  loaded,  else  FRLSE. 

«««««««««««««««««««««««««««««««««««»»«««««««««««»«/' 

{ 

char  temp [128]: 
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Listing  11-1  (continued) 

if  ( !r8rc-Joad(rfile)) 

{ 

sprlntf (temp,  "(0] (Cannot  load  file  %s  (Exiting  ...]  (OK]*,  rflle) 
fornu^iert(l,  temp) ; 
return(FflLSE) ; 

} 

return(TRUE) ; 


Application  Functions 


lnltlallze( ) 

Function:  Drau  program  screen. 

Input:  Resource  file  must  be  loaded. 

Output:  None. 

{ 

hlde^oueeO ; 

rsrc^addr(0,  NAINTREE,  &tree_^ddr); 
v/^lruk(screen_vhandle) ; 

tree^ddr(MAINTREE] -ob^  s 20;^*  moue  doun  past  menu  bar 
tree-addr(MAINTREE].olx-x  = 10; 

obJc^rau( tree^ddr,  0,  10,  0,  0,  x_max,  g_jnax); 


load  rectangle  coords 
box(0].gju  = tree^ddr(BOK0]  .ob.j4idth; 
box(0]  .g_h  tree-jaddr(BOX0]  .ob^elght; 
objc.joffset( tree^ddr,  BOX0,  &box(0].g.^,  &box(0] .g_y) ; 

box(l]  .g^  s tree^ddr(BOXl]  .Qb^ldth; 

box(l].g^  s tree_jaddr(60Xl] .ab_helght; 

objc^f fsst( tree_addr,  BOXl,  &box(l] .g...x,  &box[l].g^); 


box(2].g^  = trea^ddr(B0X2]  .ob-uildth; 

box[2].g«J>  s tree^ddr(B0X2] .ob.Jielght; 

obJc_jDffset( tree.jaddr,  B0X2,  &box(2j.g_x,  &box(2] .guy) ; 

box ( 3 ] . gu«i  = treeuaddr(B0X3]  .obuuldth; 
box(3].g^  = treeuaddr(B0X3] .ob_helght; 
objcuoffset(tree.^ddr,  B0X3,  &box(3].g_x,  &box(3] .guy) ; 


> 


shouiunouse  ( ) 
return; 
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Ustiiig  11-1  (continmed) 

move-box ( ) 

Function:  Move  a box. 

Input;  None.  Uses  tIRINTREE  and  global  variables. 

Output:  None.  Moves  box. 

{ 

I4QRD  sx,  sy,  /»  starting  coords 

fx,  Fy;  ✓*  final  coords  of  box 

graf-mouse(FLRT-HRND«  0x0L);  change  mouse  form 

obJc^ffsetC tree-add r,  FLEXBOX,  &sx,  &sy); 
graf_dragbox( tres-addr[ FLEXBOX] .ob-wldth, 
tres-addr[ FLEXBOX] .ob-helght, 

8x,  sy, 

box[0].g-x,  box[0].g-y,  box[0].g-u,  box[0].g_h, 
&fx.  &fy); 

graf-mouse(RRROIol,  0x0L);  restore  form 

redraw  parent  box  only  to  erase  current  position 
obJc_drau(tree.jaddr,  BOX0,  0,  0,  0,  x-max,  y_max); 
graf_mbox  ( treeL.addr  ( FLEXBOX] . ob-uidth , 
treeL^ddr[FLEXBOX]  -obL-helght, 
sx,  sy,  fx,  fy); 

y*  sat  new  location  relative  to  parent 

tree^jaddr [ FLEXBOX ] .ob-x  +=  (fx  - ax); 

tree-addr(FLEXBOX].ob.jy  +=  (fy  - sy); 

✓»  redraw  object 

obJC-draw(tree.jaddr,  FLEXBOX,  10,  0,  0,  x-max,  y_max); 
return; 

} 

slze-boxO 

Function:  Change  size  of  box. 

Input:  None.  Uses  MRINTREE  and  global  variables. 

Output:  None.  Moves  box. 

{ 

WORO  sx,  sy,  starting  x,y 

new-uldth,  new-helght;  ending  size 

static  I40R0  mln_jj  s 0,  smallest  size  of  box 

roin_h  = 0; 

y*  set  minimum  values  on  first  time  through 
y*  minimum  values  are  Initial  values  of  FLEXBOX  *y 
If  (mln-u  ==  0 &&  mln-h  0) 

{ 
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Ustiiig  11>1  (continited) 

mlrxjui  s tree^ddr[FLEXBOX]  .ob^idth; 
mlaJi  = trea^ddr[FLEXBOX]  .obJieight; 

> 

graf-jnou8B( POINT-HAND,  0x0L);  change  mouse  form 

objcuof fset(  treo^ddr,  FLEXBOX,  &sx,  &sy); 

graf— rubberbox(sx,  sy,  miruj*i,  min_h,  &neu-uidth,  &neu-height) ; 
graf-mouse(RRROU,  0x0L);  restore  form 

redrau  parent  box  only 

obJc^rauCtrea^ddr,  BOX0,  0,  0,  0,  x-max,  y-max); 

test  if  neu  size  Is  greater  than  enclosing  box 
if  ((neuuuldth  + tree^ddr[FLEXBOX] -ob-x)  > 
tree-jaddr  [ BOX0  ] . ob-wld  th ) 

< 

neu-uldth  = If  so,  set  to  box  edge 

tree-addr[BOX0]  .ob-uidth  - treai^ddr[FLEXBOX]  «ob^; 

) 

if  ((neu-helght  ♦ t ree-addr[ FLEXBOX ] .ob_jy)  > 
t r eeuaddr [ BOX0 ] . ob-he igh t ) 

< 

neu-helght  = if  so,  set  to  box  edge 

tree-addr(BOX0].obJielght  - tree_jaddr[FLEXBOX] .ob^; 

> 

sot  neu  uidth 

tree-addr[ FLEXBOX ].ob-uidth  » neu^ldth; 
troe-addr[FLEXBOX] .ob-height  = nouuholght; 

mov/e  size  box 

tree^ddr  [SIZEBOX]  .ob-x  » 

tree^ddr [ FLEXBOX ] .ob-juldth  - tree^ddr(SlZEBOX]  .okLJUldth; 
tree-addr[SIZEBOX] .ob-y  = 

tree^ddr[FLEXBQX]  .obJielght  * tree^ddr[SIZEBOX]  .ob-height; 
/a  redrau  object 

objc-drau(tree-addr,  FLEXBOX,  10,  0,  0,  x-max,  y^ax); 
return; 

) 


hL^lida( ) 

Function:  Change  horizontal  slider. 

Input:  None.  Uses  KAINTREE  and  global  variables. 

Output:  None.  Moves  box. 

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaKaaaaaaaaaaaava/ 

{ 

register  long  val; 


y*  long  needed  for  large  uidths  *y 
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Listing  11-1  (continued) 

wal  = graf_slldBbox(trBBjddr,  HSLIDEIN,  HSLIOE,  0); 
find  nBu  X based  on  ratio:  x = uidth  * v;ai  ^ 1000 
val  *=  (trBe_^ddr[H5LI0EIN].ob_uidth  - 
trBe_addr[H5LIDE]  .obLjJidth) ; 
tree_jaddr[H5LIDE]  .ob_x  = vai  ^ 1000; 

□bJcxjdrau(treeL-addr,  HSLIDEIN,  10,  0,  0,  x_niax,  y_jnax); 
return; 

> 

v_slide( ) 

Function:  Change  vertical  slider. 

Input:  None.  Uses  NRINTREE  and  global  variables. 

Output:  None.  Moves  box. 

{ 

register  long  val;  iong  needed  for  large  heights 

val  = graf-jBlidebox(troB«addr,  VSLIDEIN,  VSLIDE,  1); 
y*  find  neu  y based  on  ratio:  y = height  * val  y 1000  *y 
val  «=  (tree^ddr[VSLIDEIN].ch_hoight  - 
tree..addr[V5LI0E]  .ob-height) ; 
tree.jddr(VSLIDE].ob.jy  = (val  1000); 
obJc_idraij(  tree^ddr,  VSLIDEIN,  10,  0,  0,  x^ax,  y^ax); 
return; 

> 

uatch^ox( ) 

«««««««««««««««« 

Function:  Change  uatch  box. 

Input:  None.  Uses  MRINTREE  and  global  variables. 

Output:  None.  Moves  box. 

{ 

if  mouse  released  in  box  then  change  text  *y 

if  (graf.^atchbox(treeLjaddr,  URTCHBOX,  SELECTED,  NORMRL)) 

< 

if  (strcmp(  tree.jaddr[URTCHTXT]  .ob^pec,  "Off”)  ==  0) 
strcpy ( treeLjaddr [URTCHTXT ] .ob^pec,  "On  " ) ; 

else 

strcpy(  tree^ddr[NRTCHTXT}  .ob-spec,  "Off  ) ; 

> 

tree^ddr[URTCHBOX]  .ob^tate  = NORMRL; 

obJc.jdrau( tree-add r,  B0X2,  10,  0,  0,  x-max,  y-max); 

return; 

> 

control ( ) 

Function:  Master  control  function. 
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Usniig  11-1  (continiied) 

Input:  None.  Program  initialization  must  be  done  before 

entering  this  function. 

Output:  None.  Returns  for  normal  program  termination. 


{ 

OBJECT  ^menuLjaddr; 

UORD  meux,  mevy, 

meubut, 
keystate, 
keycode, 
mb return, 
meg_buf [8] ; 

UORD  euent, 

euent.fiag, 
mi_fiag  = 0, 

ml_x,  ml^,  ml^,  ml_h, 
menu-index; 


address  for  menu 
evnt-muiti  parameters 


message  buffer 
evnt-muiti  result 
events  to  look  for 
y*  0 for  entry  to  rectangle, 

1 for  exit  to  rectangle  *y 
y*  rectangle  for  Ml  event 
y*  keyboard  menu  title  selected  *y 


y*  get  address  of  menu  *y 

rsrc.jgaddr(0,  MRINMENU,  &menuuaddr); 

y*  display  menu  bar 

menu-bar (menu-addr,  TRUE); 


{ 

event  = evnt-multi(  event— flag. 


0,  y* 

01,  y* 

1, 

ml-flag,  y* 

box(3].g-x,  box[3].g-y,  y* 
box[3].g-u,  box[3].g-h, 

0,  y* 

0,  0, 

0,  0s 

msg-buf, 

0,  0s 

&mevx,  &mevy,  y* 

&mevbut,  y* 

&keystate,  y* 

&keycode,  y* 

&mbreturn);  y* 


I MU-MESRG); 

continue  loop  until  quit  *y 


It  mouse  clicks  ^y 

mouse  buttons  of  interest 

button  stats  *y 

first  rectangle  flags  *y 

x,y  of  1st  rectangle  *y 

height,  uidth  of  1st  rect  *y 

second  rectangle  flags  *y 

x,y  of  2nd  rect  *y 

u,h  of  2nd  rect  *y 

message  buffer  *y 

lou,  high  uords  for  timer  *y 

x,y  of  mouse  event  *y 

button  stats  at  event  *y 

status  of  keyboard  at  event  *y 

keyboard  code  for  key  pressed  ^y 

U times  mouse  key  enter  state  *y 


y*  wait  for  a message  indicating  a menu  selection  *y 
event-flag  = (WUJBUTTON  | KUJ11 
for(;;) 


if  (event  & MULME5R6) 

< 

if  (msg-buf [0]  !»  MNJ5ELECTE0)  not  a menu  message  *y 

continue;  y^  then  ignore  *y 
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Listing  11-1  (eontbraed) 

if  (m8gJ3uf[4]  ==  QUIT} 

break;  exit  loop 

swltch(msgJbuf[4J)  find  object  index 

< 

case  INFO:  info  selected 

break;  ignore 

default: 

break; 

> 

reset  title  state 

m8nu_tnormal(menLLjaddr,  msg  huf[3],  1]; 
menu-bar ( menu-addr , TRUF ) ; 

} end  message  handler 

if  (event  & MU-BUTTON) 

{ 

if  (mevbut  I 01)  button  pressed  down 

{ y*  find  where  event  occurred  *y 

switch  (obJc_f ind( tree-addr,  MflINTREE,  10,  mevx,  mavy)) 

{ 

case  FLEXBOX:  the  box  itself 

case  FLEXBOXl:  y*  1st  text  line  in  box  *y 

case  FLEXB0X2:  y*  2nd  text  line  in  box  *y 

move— box ( ) ; 
break; 

case  SIZEBOX: 

size-box ( ) ; 
break; 

case  HSLIOE: 

h-slide( ) ; 
break; 

case  V5LIDE: 

V— slide ( ) ; 

break; 

case  URTCHBGX: 

uatchJbox(); 

break; 

default: 

break; 

i 

} 

} y*  end  button  handler  *y 


if  (event  & MULMl) 

< 
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Listing  ll'l  (continued) 

if  ( !ml— flag)  entorod  rectangle 

{ set  to  alternate  mouse 

graf^ouse  ( HQURGLR5S,  0x0L ) ; 
ml.flag  = 1;  wait  to  exit 

euent-flag  = MULMl;  only  event 

> 

else 

{ 

gra  f-jRouse  ( RRROU , 0x0L } ; 

ml^flag  = 0;  wait  for  entry 

event-flag  = (MU-BUTTQN  | MU_M1  | MLU«IESfiG); 

> 

} 

} end  Infinite  loop 

return; 

) /-It  end  function 

Main  Program 


main( ) 

< 

int  ap— id;  application  Inlt  verify 

WORD  gr-wchar,  gr_hchar,  values  for  VDI  handle 

gr-ubox,  gr_hbox; 

Initialize  GEM  Recess 


ap— Id  = appl— init();  Initialize  RES  routines 

if  (ap-id  < 0>  no  calls  can  be  made  to  RES 

< use  GEMDQS 

Cconws("»**>  Initialization  Error,  (^^»*^n"); 

Cconws( "Press  any  key  to  continue. ^n" ) ; 

Crawcln( ); 

exit(-l);  set  exit  value  to  show  error 

> 

screen-phandle  = Gat  handle  for  screen 

graf-handle(&gr-uchar,  &gr-hchar,  &gr-ubox,  &gr_hbox); 
screeriL-vhandle  = open— vwork(screeriL.phandla) ; 
set.jscreerLjattrn ; Get  screen  attributes 

Rpplication  Specific  Routines 


if  ( lload— rBsource(  "MOUSE.RSC" ) ) no  resource  file  loaded 

exlt(l); 
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listing  11>1  (continued) 

initlalize( ) ; 
control ( ) ; 

Program  Clean-up  and  Exit 

Ualt  for  keyboard  before  exiting  program 
rsrc-freeC ) ; 

v/^lsv/uk(ecreeruuhandle) ; close  workstation 

appl— Bxlt();  end  program 

> 


Once  the  new  root  coordinates  eire  set  the  screen  can  be  drawn. 
The  o1^c.diaw()  function  draws  an  object  tree  as  seen  earlier.  In 
initialize! ),  obJc_diaw( ) starts  at  the  root  of  MAINTREE  and  goes  ten 
levels  deep.  The  clipping  rectangle  used  is  the  entire  screen  from  (0,0) 
to  (zmaz,ymaz).  After  the  tree  coordinates  are  set  the  box  coordinates 
can  be  determined.  To  use  with  the  event  library  routines,  these 
values  must  be  in  screen  coordinates.  However,  the  objects’  coor- 
dinates are  relative  to  their  parents.  The  x and  y coordinates  of  the 
object  need  to  be  converted  to  screen  coordinates.  Function 
objc-ofGswt( ) of  the  object  library  provides  this  feature.  Given  the  tree 
address  and  the  object  index,  o1^c-offiset()  returns  the  x and  y 
screen  coordinates.  The  width  and  height  remain  the  same  because 
they  are  not  affected  by  the  position  of  the  object.  The  coordinates  of 
each  of  the  four  boxes  Is  loaded  Into  the  array  box.  This  completes  the 
Initialization  and  the  mouse  is  turned  back  on. 

Function  oontrol( ) starts  ty  locating  the  menu  and  displaying  the 
menu  bar.  The  parameters  of  evnt-multi( ) warrant  some  closer  ex- 
amination. The  event- flag  variable  holds  the  events  that  the  program 
wants.  When  the  mouse  button  Is  pressed,  the  user  must  be  tiying 
to  select  something  on  the  screen.  Therefore,  a button  event  is  re- 
quired. When  the  mouse  enters  BOX3,  the  mouse  form  should  change 
so  a mouse  event  Is  also  required.  Finalfy,  the  user  may  select  a menu 
Item,  which  means  a message  event  must  also  be  included.  The 
reason  for  using  a variable  as  the  event  flag  holder  Is  that  during 
normal  processing,  the  application  may  want  to  look  for  different  sets 
of  events.  By  using  a variable,  the  events  accepted  can  be  set  while 
the  program  Is  running.  This  contributes  to  a more  dynamic  and 
modular  design.  For  example,  when  the  mouse  enters  BOX3,  It  can 
do  nothing  imtll  it  exits  the  box.  Therefore,  when  the  mouse  leaves 
the  box,  the  onty  event  that  must  be  waited  on  is  a mouse  event 
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After  the  event  flag  has  been  set  the  next  three  parameters  for 
evnt-multi( ) control  the  button  event  The  number  of  mouse  clicks 
Is  0 because  a single  press  is  all  that  is  required.  Since  the  mouse 
button  of  interest  is  the  left  button  only,  the  value  1 (bit  1 is  set)  is 
used  for  this  parameter.  The  button  state  parameter  indicates  that 
the  left  button  down  is  the  state  of  interest  (bit  1 is  again  set). 

The  next  five  parameters  control  the  first  mouse  event  The  variable 
ml-flag  is  initialized  to  0 to  indicate  that  a mouse  event  will  occur 
when  the  mouse  enters  the  area.  The  recftmgle  position  and  size  are 
in  element  3 of  the  box  array.  Since  there  is  no  second  box  of  interest 
the  next  five  parameters  are  set  to  0.  You  have  alreacfy^  seen  and  used 
the  remaining  parameters  in  the  previous  programs. 

Each  event  type  is  handled  separately.  If  the  event  is  a message, 
onfy  menu  messages  are  processed.  All  other  types  of  messages  are 
ignored.  If  the  menu  selection  corresponds  to  QUIT,  the  Infinite  loop 
is  «dted.  If  the  messeige  corresponds  to  INFO,  the  message  is  ignored 
and  the  menu  title  is  reset  If  an  information  dialog  box  does  exist  it 
can  be  displayed  here.  These  are  the  only  two  menu  selections  that 
the  program  must  look  for. 

A button  event  indicates  that  the  user  vrants  to  manipulate  some- 
thing on  the  screen.  When  a button  event  occurs,  the  program  checks 
which  button  is  pressed.  Actually,  only  button  1 should  cause  an 
event  based  upon  the  parameters  for  evnt-miilti( ).  After  the  button 
number  is  checked,  the  program  needs  to  find  where  the  mouse  was 
located  when  the  button  was  pressed.  It  obvious^  was  not  pressed  in 
the  menu  bar,  because  the  AES  would  already  have  handled  that  It 
could  have  been  pressed  somewhere  in  the  work  area.  To  find  if  the 
mouse  was  over  an  object  function  o1:jc-find()  is  used.  Function 
oljc-fiiid( ) searches  through  a tree  to  see  if  any  objects  are  located 
at  the  button  dovm  event  position.  This  function  can  start  searching 
from  any  object  in  the  tree  (not  just  the  root)  and  can  continue  for 
any  number  of  levels.  If  otjc_find()  finds  an  object  at  the  given 
location,  it  returns  the  index  of  the  object  If  no  objects  in  the  tree 
are  located  under  the  coordinates  given,  otjc-findO  returns  —1.  In 
MOUSE,  otjc-find()  is  used  as  the  control  variable  for  a switch 
statement  The  various  cases  are  selected  based  upon  the  object  index. 

If  the  user  wants  to  move  the  box  In  BOXO,  the  mouse  must  be 
located  on  object  FI/EXBOX.  However,  FLEXBOXl  and  FLEXBOX2 
cover  part  of  FLEXBOX  so  these  two  objects  also  cause  a move 
condition  to  be  activated.  To  move  the  box,  application  function 
move-tMUi( ) is  called.  If  the  user  wants  to  resize  this  box  in  BOXO, 
the  mouse  must  be  located  inside  SIZEBOX.  To  change  the  sb%  of 
the  box,  application  function  size.1ios( ) is  caUed. 

To  move  the  horizontal  slider,  the  user  places  the  mouse  over  the 
HSLIDE  object  and  presses  the  mouse  button.  In  this  case,  applica- 
tion function  h_slide( ) is  called.  If  the  mouse  is  located  on  the  vertical 
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slider,  T-slideO  Is  called.  If  the  mouse  is  in  object  WATCHBOX, 
watch-boz( ) is  cetlled.  Any  other  objects  or  —1  is  processed  through 
the  de&ult  case  and  ignored. 

The  final  event  accepted  by  event_miilti( ) Is  a mouse  event  This 
occurs  when  the  mouse  enters  BOX3.  If  ml-flag  is  0,  the  event 
occurred  when  the  mouse  entered  the  rectangle.  Therefore,  the 
program  changes  the  mouse  form  to  an  alternate  mouse  form  (here, 
to  the  HOURGLASS,  which  Is  actually  the  bumble  bee  on  the  Atari 
ST).  The  grailmou8e( ) function  changes  the  image.  The  program  now 
waits  until  the  mouse  exits  this  box;  all  other  events  are  ignored. 
Therefore  the  event-flag  is  set  to  MU-Ml  only  and  ml-flag  is  set  to 
1 (to  wait  for  an  exit).  When  the  mouse  exits  the  box,  another  mouse 
event  occurs.  In  this  case,  ml-Hag  is  set  to  1.  The  program  changes 
the  mouse  back  to  the  arrow  form,  the  ml-flag  is  set  to  0,  and  the 
event-flag  has  the  button,  mouse,  and  message  events. 

Now  that  all  the  events  have  been  handled,  look  at  the  application 
functions.  Start  with  fimction  move_box( ).  When  a box  is  going  to 
be  moved,  the  GEM  Interface  requires  the  program  to  change  the 
mouse  form  to  indicate  the  function  being  performed.  While  moving 
a box,  the  mouse  form  should  be  the  open  hand.  The  first  statement 
in  moTO-bord ) changes  the  mouse  form  to  a FLAT-HAND.  While  the 
user  is  positioning  the  box,  your  program  should  dlsplsqr  an  outline. 
The  graf-diagboxO  function  is  used  to  drag  an  outline  of  the  box 
around  on  the  screen.  Function  gtaC-diagbox( ) needs  to  know  the 
starting  coordinates  of  the  box  in  screen  coordinates.  Thus, 
objc-offi>et( ) is  used  to  get  the  starting  screen  coordinates  (the  box’s 
current  position).  Function  graf-dragboz()  is  then  called.  Its 
parameters  are  the  width  and  height  of  the  box,  the  starting  coor- 
dinates, a boundary  rectangle,  and  two  variables  to  hold  the  final 
coordinates.  The  boundary  rectangle  limits  the  area  in  which  the 
outline  may  travel.  In  MOUSE,  the  box  should  not  move  outside  of 
BOXO.  When  the  user  releases  the  mouse  button,  graf-dnigboz( ) 
returns  with  its  last  two  parameters  containing  the  final  coordinates 
of  the  box.  At  this  point  the  mouse  form  must  be  restored  to  the 
arrow  form  and  the  program  needs  to  update  the  screen. 

There  are  two  methods  for  updating  the  screen.  The  first  method 
redraws  just  the  area  affected.  First  the  program  redraws  BOXO.  TTiis 
causes  all  the  contents  of  BOXO  to  be  erased  (actually  written  over). 
Next  it  draws  a box  moving  from  the  old  position  to  the  new  position. 
Then  it  redraws  the  moved  box  at  its  new  location.  Program  MOUSE 
uses  this  first  method.  To  redraw  just  BOXO,  function  ol^c-diaw( ) is 
used.  The  drawing  starts  at  BOXO  and  continues  for  0 levels,  which 
causes  just  BOXO  to  be  drawn.  Then  function  grafLmbosf ) is  used  to 
show  a moving  outline.  Next  the  new  object  coordinates  are  set  Since 
there  is  no  function  to  go  from  screen  to  relative  coordinates,  the 
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easiest  way  to  handle  the  problem  Is  to  change  the  object’s  coordinate 
by  the  distance  moved.  Finally,  otjlc-diawl ) is  called  again  to  draw 
the  PLE2CBOX  and  all  its  children  at  the  new  location. 

The  other  method  would  be  to  calculate  the  object's  new  relative  x 
and  y position.  Use  gca£-mbox( ) to  show  a moving  box,  and  then  call 
ot(jc-draw( ) to  draw  BOXO  and  all  of  its  children.  Because  BOXO  is 
drawn  first  (parents  are  drawn  before  their  children),  it  erases  the 
area.  Then  FLEXBOX  is  drawn  at  its  new  location.  It  is  a matter  of 
convenience  and  preference  to  go  one  way  or  another. 

When  changing  the  size  of  an  object,  the  user  places  the  mouse  at 
the  lower  right  comer  of  the  object  and  presses  the  mouse  button. 
The  mouse  form  changes  to  a pointing  hand,  a mbber-box  outline 
appears,  and  the  user  can  change  the  size  of  the  object  A program 
may  place  restrictions  on  the  minimum  and  maximum  size  of  the 
box.  In  MOUSE,  the  minimum  size  of  the  box  is  the  height  of  the  two 
text  lines  and  the  width  of  the  two  lines.  The  maximum  size  is  set  so 
that  the  box  does  not  exceed  the  limits  of  BOXO.  Once  the  new  size 
has  been  set  and  verified,  a growing  box  outline  is  drawn  and  the 
object  is  redrawn  with  its  new  size. 

In  fimction  size-bos(),  the  first  statements  determine  the  mini- 
mum size  of  the  box.  liie  program  could  use  the  width  and  height 
values  of  the  text  strings  to  calculate  the  minimum  size.  However, 
MOUSE  assumes  that  the  original  size  of  FLEXBOX  is  the  minimum 
size  to  use.  You  can  go  back  and  change  the  resource  file  to  set 
FLEIXBOX  to  any  minimum  size  you  desire.  To  set  the  minimum  size. 
size-boz( ) uses  the  static  variables  min_w  and  mln-h.  On  the  first 
time  through  size-boz( ),  these  variables  are  set  at  0 and  FLEDCBOX 
is  still  at  its  original  size.  If  this  is  the  case,  min-w  and  h are 
set  to  the  original  width  and  height  of  FLEIXBOX.  Once  the  minimum 
values  are  set  the  mouse  form  is  changed  to  the  pointing  hand. 
Function  otjc_o£Eiet( ) is  used  to  get  the  screen  coordinates  of  FLEX- 
BOX. Then  graC-rabberboz( ) is  called  to  allow  the  user  to  set  the  new 
size.  Function  graf-mbbeilKix  uses  the  minimum  width  and  height 
values  but  does  not  have  any  parameters  for  a maximum  width  and 
height  The  maximum  size  must  be  calculated  manualty,  which  is 
done  a few  statements  later.  When  the  user  releases  the  mouse 
button.  graC-rtibbeif>oz( ) returns  and  function  Bize_boz( ) resets  the 
mouse  form  to  the  arrow. 

The  same  general  redrawing  method  is  used  here  that  is  used  in 
move_box( ).  First  BOXO  only  is  redrawn  to  erase  the  area.  Then  the 
new  size  is  tested  to  see  if  it  exceeds  the  maxlmiun  boundaries.  If  the 
new  size  does  exceed  the  limits.-  the  value  is  truncated  at  the  edge  of 
the  boimdary.  For  example,  if  the  right  edge  of  FLE2CBOX  extends  past 
the  right  edge  of  BOXO.  the  right  edge  of  FLEIXBOX  is  set  to  stop  at 
the  right  edge  of  BOXO.  Note  how  the  relative  object  coordinates  are 
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used  for  this  calculation.  The  relative  x coordinate  of  FLEXBOX  plus 
its  new  width  must  be  less  than  the  width  of  BOXO.  A similar  test  is 
done  with  the  relative  y and  new  height 

Once  the  new  width  and  height  are  set  the  relative  coordinates  of 
SIZEBOX  (the  small  box  in  FLEXBOX)  must  be  changed.  Otherwise, 
it  will  appear  in  the  same  relative  position  as  before.  The  size  box 
should  always  be  in  the  lower  right  comer.  When  a box  is  resized,  the 
relative  position  of  the  lower  right  comer  changes.  Therefore,  the  new 
relative  x and  y coordinates  of  SIZEBOX  are  calculated.  Now  that  all 
the  children  of  FLEXBOX  are  set  ol^c-dfaw( ) is  called  once  again  to 
draw  FLEXBOX  in  its  new  size. 

For  the  slide  bars,  the  user  places  the  mouse  on  the  slider  and 
presses  the  mouse  button.  The  slider  can  then  be  moved  to  any 
position  within  the  slide  bar.  Control  of  the  slider  is  handled  1^ 
function  gral-8lidebox( ).  The  tree  address,  the  index  of  the  slide  bar 
object  and  the  index  of  the  slider  object  are  passed  to  gra£-slidebox( ). 
The  last  parameter  determines  whether  the  box  moves  in  the  vertical 
or  horizontal  direction.  0 indicates  horizontal  movement  and  1 indi- 
cates vertical  controL  The  gra£-slideboK( ) function  automatical^ 
keeps  the  object  Inside  its  parent  When  the  user  releases  the  mouse 
button,  the  function  returns  a value  between  0 and  1000.  This 
Indicates  the  relative  position  of  the  center  of  the  slider  inside  the 
slide  bar.  A 0 is  the  furthest  left  and  1000  is  the  furthest  right  position 
on  a horizontal  slide  bar  and  the  top  and  bottom  of  a vertical  dide 
bar.  respectively.  On  a horizontal  ^de  bar.  once  the  new  relative 
position  is  known,  the  new  x position  must  be  calculated.  Since  the 
X position  is  relative  to  the  parent,  a ratio  can  be  set  up  eis  this: 

newx  _ value  returned 
slide  bar  width  1000 

Solving  this  equation  for  the  new  x coordinate  gives  this: 

new  X = (value  returned  • slide  bar  width)  / 1000 

For  a vertical  slide  bar.  the  new  y coordinate  is  calculated  with  the 
following  equation: 

new  y = (value  returned  • slide  bar  height)  / 1000 

After  calculating  the  new  x or  y coordinate  of  the  slider,  the  value 
must  be  set  in  the  OBJECT  stmcture  for  the  slider.  Then  the  slide 
bar  is  redrawn. 

Function  h_slide( ) handles  the  request  for  change  to  the  horizontal 
slider.  Function  0ta£_slidebox( ) is  used  to  control  the  slider  move- 
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ment  When  gra£_8lidebos( ) returns,  variable  val  has  the  relative 
position  of  the  slider  in  the  slide  bar.  Variable  val  is  declared  as  a 
long  integer  because  the  multiplication  may  exceed  the  range  of  a 
standard  integer.  Note  that  the  width  of  the  slide  bar  is  adjusted  by 
subtracting  the  width  of  the  slider.  The  value  returned  by 
gra£-slidebos( ) is  the  relative  position  of  the  center  of  the  slider.  The 
center  of  the  slider  never  reaches  the  edge  of  the  slide  bar.  At  best, 
the  center  of  the  slider  gets  to  within  one-half  slider  width  of  the  end 
of  the  slide  bar.  One-half  width  at  the  left  edge  emd  one-hedf  width  at 
the  right  edge  mesins  that  there  is  one  slider’s  width  of  area  on  the 
slide  bar  that  the  center  of  the  slider  cannot  reach.  Therefore,  the 
width  of  the  slider  must  be  taken  out  because  this  width  is  a "dead 
zone”  in  which  the  slider  cannot  move.  After  calculating  the  new  x 
coordinate,  the  slide  bar  (and  its  child,  the  slider)  can  be  redrawn 
using  objc_dxaw( ).  Function  v_slide( ) is  much  the  same  except  that 
it  uses  the  y coordinate  and  the  object’s  height  It  also  adjusts  the 
total  height  of  the  slide  bar  by  subtracting  the  height  of  the  slider 
itself. 

The  leist  application  function  is  WBtch-box( ).  This  function  uses 
the  gra£-watchbos( ) function  to  see  if  an  object  button  is  selected. 
The  parameters  of  graf-watchbox( ) provide  the  address  of  the  tree, 
the  index  of  the  object  being  watched,  and  the  state  of  the  object  when 
the  mouse  is  in  and  out  of  the  box.  The  gra£_watchboz( ) function 
returns  TRUE  when  the  mouse  button  is  released  while  the  mouse  is 
inside  the  box  and  FALSE  otherwise.  The  result  of  releasing  the 
button  Inside  the  box  here  is  that  the  text  is  toggled  from  “On”  to 
‘‘Off’  or  vice  versa  When  gra£-watcbbos( ) returns,  it  leaves  the 
watched  box  in  its  last  state.  Thus,  if  you  are  emulating  a button  as 
done  in  MOUSE,  then  when  graf-watchbox( ) returns  the  box  needs 
to  be  set  back  to  its  original  state. 

This  completes  program  MOUSE.  There  are  quite  a few  changes  you 
can  make  to  this  program.  First  you  might  try  adding  an  information 
dialog  box  as  used  in  the  previous  four  programs.  Also,  function 
size_box()  did  not  use  the  gra£-g)rowbox( ) function  to  show  the 
change  of  size  for  the  box.  Use  the  move_boz()  function  as  an 
example  of  where  to  insert  the  gra£_g)rowbos( ) function.  Another  area 
to  investigate  is  the  mouse  form.  After  you  have  worked  with  the 
predefined  mouse  forms,  create  one  of  your  own  using  the  MPORM 
structure.  Look  back  at  the  raster  programs  for  examples  of  creating 
bit  maps  and  masks. 

If  your  program  changes  the  mouse  form,  it  is  responsible  for 
restoring  the  mouse  form  to  the  arrow  when  the  mouse  leaves  your 
work  area.  For  example,  a word  processing  program  uses  the 
TEXT-CRSR  mouse  form.  If  the  user  moves  the  mouse  to  one  of  the 
window  control  areas,  the  desktop,  or  the  menu  bar,  the  word  proces- 
sor is  responsible  for  changing  the  mouse  form  back  to  the  arrow. 
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The  easiest  way  to  handle  this  in  a program  is  to  set  up  a mouse 
event.  When  the  mouse  leaves  the  work  area,  the  mouse  event  occurs 
and  your  program  can  change  the  mouse  form.  While  the  mouse  is 
outside  the  work  area,  your  program  waits  for  the  mouse  to  enter  the 
work  area  (the  reverse  procedure  as  shown  in  program  MOUSE  for 
BOX3).  When  the  mouse  returns  to  the  work  area,  the  mouse  form 
can  be  set  to  whatever  form  is  required.  This  should  be  done  to 
remain  consistent  with  the  GEM  interface. 

In  this  chapter,  you  have  seen  some  more  events,  partlculariy  mouse 
and  button  events,  and  some  of  the  basic  routines  used  by  the  AES 
in  its  gr£q)hics  interface.  These  routines  are  useful  when  you  want  to 
provide  graphic  tools  for  the  user  to  set  such  as  the  control  panel 
accessory.  The  next  chapter  shows  the  use  of  windows,  which  is  the 
primary  use  of  many  of  these  graphic  routines. 


CHAPTER  TWELVE 


Windows  on 
the  World 


By  now,  you  have  probably  noticed  that  the  programs  written  so  far 
lack  one  primaiy  aspect  of  the  GEM  environment:  the  use  of  windows. 
Most  programs  have  used  Just  the  desktop  window,  which  Is  the 
default  location  for  most  output  functions  accessed  by  the  programs. 

The  use  of  windows  In  a program  provides  a more  natui^  working 
environment.  A window  allows  the  user  to  separate  tasks  and  or- 
ganize them  on  the  screen  in  any  order.  For  example,  a word  proces- 
sor may  allow  two  or  three  different  windows  to  be  open  with  each 
window  editing  a different  file.  When  the  user  Is  working  on  one  file 
and  needs  Information  from  another  file.  It  is  then  a simple  matter 
to  take  the  Information  needed  from  one  window  and  transfer  it  to 
the  original  window. 

There  are  a number  of  different  situations  that  the  program  must 
deal  with  when  using  a window.  This  chapter  covers  the  use  of 
windows  In  a program,  how  a program  can  create  and  provide  a 
window  for  the  user,  and  how  the  program  must  communicate  with 
the  AES  to  handle  window  operations.  Finalfy,  two  demonstration 
programs  show  the  use  of  the  many  window  concepts  that  are  dis- 
cussed. 


Window  Rules 


Chapter  9 introduced  the  components  of  a window.  These  com- 
ponents are  shown  again  in  Figure  12-1.  The  components  include  the 
close  box,  full  box,  title  bar  and  move  bar,  scroll  bars,  sliders,  arrows. 
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size  box,  and  work  area.  The  title  bar  and  work  area  are  the  only 
required  components  for  a GEM  window.  All  other  components  may 
or  may  not  appear  depending  on  the  application  that  creates  the 
window.  To  quickly  review  the  components,  the  user  selects  the  close 
box  to  indicate  to  the  application  that  the  window  is  to  be  closed  and 
removed  from  the  screen.  The  full  box  toggles  the  size  of  the  window 
between  the  largest  possible  size  and  the  normal  size  of  the  win- 
dow. The  size  box  allows  the  user  to  change  the  dimensions  of  the 
window.  The  move  bar  allows  the  user  to  move  the  window  on  the 
desktop.  The  scroll  bar.  sliders,  and  arrows  move  the  window  over  the 
data  being  displayed.  The  arrows  move  the  window  up  and  down  or 
left  and  right.  The  size  of  the  slider  relative  to  the  scroll  bar  is  propor- 
tional to  the  size  of  the  window  relative  to  the  total  size  of  the  file. 

When  an  application  is  running,  it  is  responsible  for  the  contents 
of  the  work  area.  All  user  interactions  with  the  remaining  com- 
ponents of  the  window  are  handled  by  the  AES.  As  mentioned  egirlier, 
when  the  user  Interacts  with  one  of  these  components,  called  window 
control  areas,  the  AES  sends  a message  to  the  application  indicating 
that  the  user  has  changed  the  window  environment  in  some  way. 


The  Mndow  Manager 


Using  a window  in  a program  requires  the  use  of  the  functions 
contained  in  the  window  library  of  the  AES.  This  library  contains  the 
routines  that  create  windows,  manipulate  them,  and  set  their  at- 
tributes. Accessing  a window  is  similar  to  using  a workstation.  Each 
window  has  a window  handle  that  Identifies  the  window  to  the  AES. 
GEM  can  handle  up  to  eight  different  windows  at  one  time. 

The  desktop  itself  is  a window  even  though  it  doesn’t  look  or  work 
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like  a normal  window.  The  menu  bar  can  be  thought  of  as  the 
information  line  and  the  gray  desktop  as  the  work  area.  The  desktop 
window  always  has  a handle  with  the  value  0 (window  handles  are 
always  integers).  The  desktop  uses  one  window  so  there  are  seven 
windows  available  for  applications  and  desk  accessories.  Most  ap- 
plications use  no  more  than  four  windows  at  one  time.  Otherwise,  if 
the  application  were  to  use  all  seven  remaining  windows,  there  would 
be  no  windows  for  the  desk  accessories  to  use.  Eiven  the  desktop 
limits  the  number  of  windows  that  can  be  open  at  one  time.  For 
example,  by  double-clicking  the  floppy  disk  icon  you  can  open  a 
window  to  show  the  disk’s  directory.  You  can  keep  opening  windows 
for  the  same  floppy  disk.  However,  if  you  try  to  open  another  window 
once  you  have  opened  four  windows,  the  desktop  gives  you  a message 
saying  that  no  more  windows  are  available. 


Window  Procedures 

When  a window  is  opened,  the  AES  must  reserve  space  in  memory 
for  this  window  to  keep  track  of  the  window’s  attributes.  Therefore, 
when  you  want  to  use  a window,  you  must  follow  a particular  se- 
quence of  function  calls  to  initiate  and  use  the  window.  These  calls 
create  the  window,  open  the  window,  close  it  and  finally  delete  it 
when  it  is  no  longer  needed.  Creating  the  window  tells  the  AES  to 
reserve  memory  space  for  a new  window.  The  creation  process  also 
defines  the  size  and  components  of  the  window.  Opening  the  window 
causes  the  AEJS  to  draw  the  window  on  the  screen.  The  AES  takes 
care  of  drawing  the  control  areas.  The  work  area  is  left  blank  to  be 
filled  in  by  the  sqrpllcation.  When  the  window  is  no  longer  needed  on 
the  screen,  the  program  must  close  the  window.  This  removes  the 
window  from  the  screen.  Any  data  underneath  the  window  is  then 
displayed.  If  the  window  is  no  longer  needed,  it  is  deleted  from  the 
AES  so  that  another  window  is  available  for  a program  or  desk 
accessory. 

In  GEM,  the  window  that  is  completely  visible  is  called  the  top- 
most, or  active,  window.  This  Is  the  window  currently  being  accessed 
by  the  user.  Other  windows  are  partially  or  complete^  hidden  ty  the 
active  window.  These  other  windows  remain  inactive  until  the  topmost 
window  is  closed  or  the  user  selects  one  of  the  Inactive  windows.  If  the 
topmost  window  is  closed  or  removed  from  the  screen,  the  wlndowjust 
below  it  becomes  the  active  window.  If  the  user  clicks  another  window, 
that  window  becomes  the  topmost  window. 

Because  of  the  number  of  different  conditions  that  might  occur, 
programs  with  windows  must  be  event-driven.  Once  the  program  has 
created  and  opened  a window,  it  waits  for  messages  from  the  AEIS. 
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When  the  user  interacts  with  a window  control  area,  the  AES  sends  a 
message  informing  the  program  of  the  request  The  program  then 
updates  the  window  according  to  the  user’s  requests.  Ihe  program  is 
re^H>nsible  for  any  user  interaction  with  the  work  area. 

Window  Mcutager  Routines 

The  window  manager  (window  library)  consists  of  a set  of  routines 
that  allow  an  application  to  manipulate  a window.  These  routines 
include  wind-cieate( ).  wind.j(qpen( ),  wind_close( ).  wind_ddete( ). 
wind-calc().  wind-get().  wind_set().  wiiid-find().  emd  wind_iq»- 
date(). 

Function  wind_create( ) allocates  space  for  a window  and  returns 
a handle  to  that  window.  The  wind_open( ) function  opens  a window 
on  the  desktop  to  a specified  size.  In  addition,  this  function  generates 
an  event  that  causes  the  application  to  draw  the  work  Euea.  The 
wind-clo8e( ) function  simply  closes  a window  and  removes  it  from 
the  screen.  This  function  also  causes  the  appropriate  events  to  occur 
so  that  the  Images  underneath  the  window  (which  are  now  visible) 
can  be  redrawn.  Function  wind_ddete( ) removes  a window  from  the 
AES  and  allows  the  handle  to  be  reused  by  another  £q>pllcatlon. 

There  are  two  rectan^es  associated  with  a window  that  are  of 
interest  to  em  £q)pllcatlon.  The  first  rectangle  is  the  work  areei.  The 
work  area  rectangle  is  slmpfy  the  part  of  the  window  labded  as  the 
work  area  (see  Figure  12-1).  As  the  window  is  moved  and  sized,  the 
work  area  rectangle  changes  its  size  and  position.  The  second  rec- 
tangle. the  border  area  is  the  total  area  of  the  window  including  the 
work  area  and  all  the  control  areas.  Function  wind_calc( ) calculates 
the  border  area  given  the  work  area  of  the  window  and  vice  versa. 

Functions  wind_gd( ) and  wind_set( ) allow  an  sq)plication  to  get 
and  change  Information  about  a specific  window.  Function  wlnd-getf ) 
returns  such  information  as  the  position  and  size  of  the  work  area 
or  the  border  area,  the  size  of  a full  window  (that  is.  when  the  full 
box  is  selected),  the  position  of  the  sliders,  the  size  of  the  diders.  and 
the  handle  to  the  active  window.  Function  wind_set( ) is  the  opposite 
of  wlnd_get( ).  It  allows  the  application  to  change  the  window’s  ap- 
pearance such  as  changing  its  title,  changing  the  contents  of  the 
information  line,  setting  the  position  and  size  of  the  entire  window, 
and  setting  the  sliders  and  slider  sizes. 

Function  wind_fihrd( ) returns  the  handle  of  a window  under  the 
coordinates  given  as  Its  parameters.  Function  wind_iqtdate( ) teOs  the 
A£^  that  the  application  is  about  to  update  a window  or  has  com- 
pleted the  update.  This  function  is  used  so  that  when  the  program  is 
updating  a window,  the  program  does  not  receive  any  other  events 
that  would  change  the  window’s  £q>pearance.  This  stops  all  window 
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processing  until  the  ^plication  has  completed  redrawing  the  win- 
dow. liniid_iq>date( ) also  allows  an  implication  to  take  control  of  the 
mouse  functions  or  return  control  to  the  AES.  Taking  control  of  the 
mouse  functions  means  that  the  implication  program  must  handle 
the  processes  normally  performed  by  the  screen  manager  such  as 
following  the  mouse,  controlling  the  menus,  and  controlling  the  win- 
dow components. 

The  sample  programs  presented  in  this  chapter  utilize  most  of 
these  functions.  The  first  program,  WINDOWl,  is  a ^neral  introduc- 
tion to  using  windows  in  a program.  The  second  program.  WINDOWS, 
shows  how  an  application  handles  the  remaining  components.  Each 
program  is  designed  to  allow  you  to  experiment  with  the  window 
functions. 


Window  Messages 

As  mentioned  above,  a program  manages  its  windows  on  an  event 
basis;  that  is,  an  event  determines  the  next  process  that  needs  to  be 
performed.  The  AES  conummicates  to  the  application  through  mes- 
sage events.  These  messages  are  generated  when  the  application’s 
window  becomes  the  new  top  window,  the  application’s  window  has 
been  closed,  the  full  box  is  selected,  and  so  forth.  Essential^,  a 
message  is  sent  in  response  to  emy  user  interaction  with  a window 
control  area  or  when  the  work  area  needs  to  be  redrawn.  The  contents 
of  the  message  simpty  Inform  the  application  of  what  the  user  has 
requested.  For  example,  for  the  application  to  make  a new  top  window, 
the  application  must  set  that  window  as  the  top  window  using 
wind-setf).  The  AES  then  responds  by  redrawing  that  window’s 
control  areas  as  the  top  window  and  issuing  a redraw  message  to  the 
application  owning  the  window  (that  is,  the  application  that  created 
the  window). 

A close  message  requires  the  application  to  close  the  window. 
Opening  or  closing  a window  may  also  require  other  aspects  to  be 
changed.  For  example,  when  the  last  window  is  closed  in  an  editor 
program,  the  Save  or  Save  As.,  options  should  be  disabled  because 
there  is  no  more  data  to  save. 

The  full  box  selection  requires  the  application  to  determine  whether 
the  window  Is  at  Its  full  size  or  not  If  It  is  at  its  full  size,  the 
application  must  use  wind_set( ) to  reset  the  size  of  the  window  to 
its  original  smaller  size.  If  the  window  is  at  its  smaller  size,  the 
application  must  reset  the  window  to  Its  full  size.  If  sliders  are  used 
on  the  window,  changing  the  size  of  the  window  also  requires  that 
the  relative  size  of  the  sliders  be  changed.  As  the  window’s  size 
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increases  or  decreases,  the  size  of  the  scroll  bar  also  increases  or 
decreases.  The  slider  size  must  be  changed  to  maintain  the  correct 
proportions. 

An  arrow  message  indicates  that  the  user  has  selected  one  of  the 
directional  arrows  at  the  ends  of  the  scroll  bars.  When  an  arrow 
message  is  received,  the  application  must  move  the  window  one  unit 
in  the  direction  of  the  arrow.  For  a text  screen,  this  would  be  one  line 
up  or  down  or  one  character  left  or  right  For  a spreadsheet  applica- 
tion, this  would  be  one  row  up  or  down  or  one  column  left  or  right 
If  the  scroll  bar  is  clicked  (this  is  also  indicated  by  an  arrow  message), 
the  window  should  move  one  screen  width  at  a time.  If  the  sliders  are 
moved,  the  supplication  needs  to  calculate  what  portion  of  the  data  to 
display. 

Moving  or  resizing  a window  such  as  the  rubber-box  and  drag-box 
outlines  is  handled  by  the  AES  for  the  graphic  display.  When  the  user 
releases  the  mouse  button,  the  move  or  resize  message  is  sent  to  the 
application.  The  message  contains  the  new  position  or  size  of  the 
window.  The  application  should  check  that  the  window  has  not 
become  too  small.  The  wind_8et( ) function  is  also  used  here  to  set 
the  new  position  or  size.  If  the  size  of  the  window  is  changed,  the  size 
of  the  sliders  must  be  checked. 

Finally,  a redraw  message  indicates  that  a portion  of  the  window 
work  area  has  now  become  visible.  The  application  is  responsible  for 
filling  this  ne^^y  visible  area. 


Redrawing  a Window 


A window  on  the  screen  may  have  a visible  portion.  Any  such  visible 
portion  of  a window  can  be  represented  by  a set  of  nonintersecting 
rectan^es.  Figure  12-2  shows  a set  of  five  rectangles  that  represent 
the  visible  portion  of  window  B.  The  AES  maintains  a list  of  nonin- 
tersecting rectangles  that  cover  the  visible  portion  of  an  open  window. 
A redraw  message  will  be  issued  for  each  window.  A redraw  message 
contains  the  area  of  the  screen  to  be  redrawn  and  the  handle  of  the 
window  to  redraw.  For  example,  if  the  top  window  in  Figure  12-2  is 
closed,  there  would  be  a rectangular  £u^  (the  area  prevlou^y  covered 
by  the  window)  to  be  redrawn.  Closing  the  window  causes  the  AES  to 
issue  a redraw  message  to  the  appllcation(s)  owning  windows  A and  B. 
The  same  application  may  own  both  windows  A and  B but  not 
necessarily.  It  is  the  responsibility  of  the  application  program  to  then 
redraw  the  woiic  area  portion  of  the  window. 

When  the  top  window  is  closed,  the  visible  area  for  window  B 
increases.  Therefore,  the  AES  changes  the  visible  rectangle  list  (see 
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Figine  12-2  Window  B’b  Visible  Rectangle  List 

Figure  12-3)  and  sends  a redraw  message  to  the  application  owning 
this  window.  To  draw  a window,  only  those  visible  portions  should  be 
output  to  the  screen.  This  can  be  accomplished  by  setting  the  clipping 
rectangle  to  one  of  the  visible  rectangles  in  the  rectangle  list  Anything 
outside  of  the  clipping  rectangle  would  not  be  drawn.  By  going 
through  each  rectangle  in  the  list  the  entire  visible  portion  of  a 
window  can  be  drawn.  However,  it  could  become  quite  time-consum- 
ing for  an  sq>plication  to  redraw  an  entire  window  when  only  a small 
portion  needs  to  be  redrawn  as  in  Figure  12-3.  To  speed  the  process 
of  redrawing  a window,  the  clipping  rectangle  is  set  to  the  intersec- 
tion of  the  redraw  area  and  the  visible  rectangle.  In  the  figure, 
rectangle  1 intersects  with  the  redraw  area  in  the  lower  right  comer. 
The  clipping  rectangle  is  set  to  this  intersection.  When  the  window 
is  redrawn,  only  the  image  in  this  intersection  is  output  Rectan^es 
2, 3.  and  4 do  not  intersect  with  the  redraw  area  at  all  so  no  redrawing 
is  done.  The  left  half  of  rectangle  5 intersects  with  the  redraw  area 


Figme  12-3  mndowB'B  l^sible  Rectangle  List  and  the  Redraw  Area 
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so  this  portion  of  the  window  is  output  Therefore,  the  redraw 
procedure  consists  of  intersecting  each  visible  rectangle  with  the 
redraw  area  If  an  intersection  exists,  the  clipping  rectangle  is  set  to 
the  intersection  area  and  the  window  is  drawn.  If  no  intersection 
exists,  the  next  visible  rectangle  is  used.  When  aU  visible  rectangles 
in  the  list  have  been  checked,  the  window  is  redrawn. 

An  application  usually  has  just  one  function  used  to  redraw  the 
window.  This  one  function  may  consist  of  many  other  functions;  yet, 
it  provides  a single  entry  point  to  the  window-drawing  process.  By 
having  a single  drawing  function,  the  redraw  sequence  can  make  just 
one  call  when  the  window  needs  to  be  redrawn.  Otherwise,  the  redraw 
process  becomes  cluttered  with  too  many  hmction  calls  and  the  flow 
of  the  program  becomes  obscured.  As  you  can  see,  dealing  with 
windows  is  not  the  simplest  of  tasks  and  having  a clear  program  flow 
aids  you  tremendously  when  changing  or  debugging. 


Hie  WINDOW  Structure 


The  AES  maintains  an  internal  data  structure  to  handle  window 
displays.  Through  the  wlnd_get( ) function,  you  can  retrieve  various 
values  such  as  the  position  and  size  of  the  work  or  border  eirea,  the 
position  and  size  of  the  full  size  window,  the  position  and  size  of  the 
horizontal  and  vertical  sliders,  the  handle  of  the  top  window,  the  first 
rectangle  in  a window’s  visible  rectangle  list,  and  the  next  rectangle 
in  the  window's  visible  rectangle  list  However,  neither  wind_get( ) nor 
any  other  window  functions  provides  any  further  access  to  window 
values  needed  for  the  processing  of  the  program.  Specifically,  once  the 
window  is  created,  you  cannot  retrieve  information  about  which 
control  areas  are  visible,  whether  the  window  is  visible  or  not  (that 
is,  opened  or  closed),  and  whether  the  window  is  at  its  full  size  or  not 
All  these  values  must  be  maintained  the  application. 

To  help  keep  track  of  these  window  values,  the  programs  in  this 
book  use  a structure  called  WINDOW.  (See  Figure  12-4.)  Tlie  WINDOW 
structure  is  provided  by  the  application.  It  is  not  a part  of  GEM. 
The  WINDOW  structure  holds  information  about  a window  not  readily 
accessible  through  an  AES  function.  In  addition  to  the  WINDOW 
structure,  there  is  an  array  of  WINDOW  structures  called  windows. 
This  array  holds  up  to  the  maximum  number  of  windows  specified 
by  the  application.  For  the  programs  in  this  book,  the  maximum 
number  of  windows  is  four.  When  a window  is  created  by  the  applica- 
tion, the  window’s  information  must  be  stored  in  the  array.  When  a 
window  is  deleted  by  the  application,  it  must  also  be  deleted  from  the 
windows  array.  Handling  the  windows  array  requires  some  additional 


Windows  on  the  Worid  32 1 


typedeF  struct  uind_type  { 

UIORO  handls; 

UORD  mf—typa; 

UQRO  (nf_visibls; 

UIORO  (nf_fullslze; 

} UlINDOU; 

Figaie  12-4  The  WINDOW  Stnictnre 

overhead  However,  once  you  see  the  convenience  of  having  this  array, 
you  will  agree  that  It  is  necessary. 

The  handle  field  contains  the  handle  of  the  window.  The  type  field 
contains  the  components  available  for  this  window.  Each  bit  In  the 
field  represents  a different  component  The  bit  layout  Is  discussed 
later.  The  visible  field  keeps  track  of  whether  the  window  is  open  or 
closed.  If  visible  Is  TRUE,  the  window  Is  open.  The  field  fullslze  Is 
TRUE  If  the  window  Is  at  its  full  size. 


Program  WlNDOWl 

You  should  now  be  ready  to  create  a window-exercising  ^plication. 
Program  WlNDOWl  is  the  first  step  toward  creating  an  application 
outline  file  much  like  OUTLINE.C  for  the  VDI.  Of  course,  before 
creating  a complete  application,  you  need  a resource  file. 

The  WlNDOWl  Resource  FUe 

The  resource  file  for  program  WlNDOWl  is  shown  in  Figure  12-5.  It 
contains  two  trees.  Ihere  is  a menu  named  MAINMENU  and  a dialog 
box  called  INFOBQIC  The  dialog  box,  as  shown  in  the  figure,  is  much 
like  the  dialog  boxes  shown  earlier.  The  menu  contains  the  Desk  and 
File  titles  and  a Windows  title.  Under  the  Desk  menu,  the  first  entry 
should  be  changed  to  read  “About  WlNDOWl.”  Name  this  selection  as 
INFO.  Under  the  File  menu,  there  is  the  option  Quit  to  be  named 
QUIT.  The  Windows  menu  has  four  entries,  each  to  open  one  of  four 
windows.  The  entries  are  named  WINDl,  WIND2,  WINDS,  and  WIND4. 
Once  you  have  created  this  resource  file,  save  it  imder  the  name 
WlNDOWl  .RSC. 

Overview  qf  WlNDOWl 

Program  WlNDOWl  demonstrates  how  an  application  handles  win- 
dows. Ihls  program  allows  the  user  to  open  up  to  four  windows  at 
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Rbout  UINDOUl 


Desk  Rccessopy  t 
Desk  Rccessopy  2 
Desk  Rccessopy  3 
Desk  Rccessopy  4 
Desk  Rccessopy  5 
Desk  Rccessopy  6 


U i n d o w 3 

Open 

Mindoui 

1 

Open 

Uindou 

2 

Open 

Ui ndou 

3 

Open 

M i ndou 

Rbout  UINDOUl 

This  is  the  fipst  ppogpon  uhich 
denonstpotes  the  use  of  uindous. 


Figure  12-5  Program  WINDOW!  Resource  File 

any  one  time.  The  contents  of  the  windows  are  filled  ovals  with  each 
window  using  a different  fill  pattern.  The  user  may  move,  resize,  close, 
reopen,  and  full  size  any  of  the  windows.  When  the  user  quits  the 
program,  any  open  windows  are  closed  and  all  windows  are  deleted. 

The  WINDOWl  program  is  shown  in  Listing  12-1.  Do  not  be 
alarmed  by  the  length  of  this  program.  You  have  already  seen  most 
of  the  functions  and  procedures  in  previous  programs.  Next  is  a 
description  of  some  of  the  oiganization  changes  made  to  this 
program. 

Listing  12-1  Program  WINDOWl 

UINDOUl. C Sample  ulndou  application 


This  program  demonstrates  the  use  of  ulndous  ulthin 
an  application. 


System  Header  Files  & Constants 


tUnclude  <stdlo.h> 
tlinclude  <osblnd.h> 
ttinclude  <gemdefs.h> 


Standard  10 
GEMDOS  routines 
y*  GEM  RES  »/ 
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Listing  12-1  (continned) 

ttinclude  <obdef8.h>  GEM  constants 

ttlnclude  <errno.h>  srrno  declaration 

ttdefine  FALSE  0 

Qdefine  TRUE  ! FALSE 

GEM  Application  O^/erhead 


Declare  global  arrays  for  VDI-  *>' 
typedaf  Int  WORD;  WORD  is  16  bits 

WORD  contrl[12),  VDI  control  array 

intout[128],  intin[128],  VDI  input  arrays 

ptsin[120),  ptsout[126];  VDI  output  arrays 


WORD  8creen.vhandle, 

sc  reen_phand i e , 
screen— rez, 
color— screen, 
x-inax, 
y-max, 

m-hidden  = FALSE; 


virtual  screen  uorkstation 
physical  screen  uorkstation 
screen  resolution  0,1,  or  2 
flag  if  color  monitor 
<«'*  max  X screen  coord  *<«' 
max  y screen  coord 
mouse  visibility  status 


WORD 


ttdefine 

ttdefine 


gr^char,  gr-hchar,  values  for  system  sizes 

gr— ubox,  gr— hbox; 

set  min  uindoui  size 

WMIN-WIDTH  (2»gr-ubox) 

WMIhLHEIGHT  (3»gr_hbox) 


WORD 

ap— id; 

✓K 

application  ID 

WORD 

num-tJindouis; 

✓K 

number  of  uindouis  open 

WORD 

cur-Mindoui; 

✓K 

index  for  current  uindou 

typedef  struct  uind_ type  { 

✓K 

uindou  record 

WORD 

handle; 

✓ K 

AES  uindou  handle 

WORD 

type; 

✓K 

uindou  attribute  bits 

WORD 

visible; 

/» 

flag  if  visible 

WORD 
> WINDOW; 

fulisize; 

✓ K 

flag  if  full  size 

ttdefine 

MAX-WINDOW  4 

✓K 

allou  for  4 uindous 

WINDOW 

Ufindous[  MAX-WINDOW  ] ; 

✓K 

array  of  uindou  records 

WINDOW 

desktop; 

/K 

desktop  record 

WORD 

xdssk,  ydesk, 
udesk,  hdesk; 

✓K 

desktop  area 

Application  Specific  Data 

K « K «»»  UK  K«  «iHI  i(K  K ««!(»««  «/ 
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Usting  12-1  (oondnaed) 

ttinclude  "uiindoul.h*  resource  header  file 

WORD  uilndl,  ulnd2«  uindou  indices 

uiind3,  ulnd4; 

GEh'pelated  Functions 

I4DRD  operL.vujork(physJiandie) 

I4DR0  phys-handie; 

Function:  This  function  opens  a virtual  uorkstation* 

Input:  physJiandle  s physical  uorkstation  handle 

Output:  Returns  handle  of  uorkstation. 

{ 

MORO  uork_ln(U], 

uorl<cjout[57], 

new-Jiandie;  /*  handle  of  uorkstation 

int  1; 

for  (i  = 0;  i < 10;  i++) 
uorl<-an[i]  s 1; 
work-J.n(10]  = 2; 
neuJiandie  - phys^andle; 
u^pnuuk(uork..in,  &neujiandle, 
return(neuL>iandie) ; 

> 

SB  t-jscreerua  1 1 r () 

Function:  Set  global  values  about  screen. 

Input:  None.  Uses  screerL.vhandle. 

Output:  Sets  >cjnax,  y.jnax,  color.jscreen,  and  screen^rez. 

{ 

UORD  uorl<.jout[57] ; 

vq^xtnd(screen_vhandie,  0,  uorl<_out); 
x^ax  s uork^ut[0j; 
y-max  = uorl<^ut(l]; 

screen— rez  = GetrezO;  /»  0 = lou,  1 = mod,  2 = high 

color-screen  = (screen-rez  < 2);  mono  2,  color  0 or  1 

> 

hide— mouse ( ) 

/««« »««»««!(« 

Function:  Make  mouse  invisible  if  currently  visible. 

Input:  None.  Uses  variable  m-hldden. 


set  for  default  values 

USB  raster  coords 
use  currently  open  ukstation 
uor)<-jDut) ; 
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Listing  12-1  (continued) 

Output:  Sets  nuhidden  to  TRUE. 

( 

If  ( !m_hldden) 

( 

graf_mou8e(IUDFF,  OxOL); 
m_hldden  = TRUE; 

> 

) 

shouLjnause( ) 

Function:  Make  mouse  visible  If  currently  Invisible. 

Input:  None.  Uses  cuhldden. 

Output:  None.  Sets  nuhidden  to  FRLSC. 

( 

if  (<n-hlddBn) 

< 

graf.jnou8e(MJ0N«  0x0L); 
nuhidden  = FRLSE; 

> 

> 

loacLxe6ource(rflle) 
char  *rfiie; 

Function:  Load  resource  file. 

Input:  rflle  s string  ulth  resource  filename. 

Output:  Returns  TRUE  if  file  loaded,  else  FRLSE. 

{ 

char  temp(128]; 

if  ( lrsrc.load(rflle] ) error  loading  file 

{ y*  set  alert  format 

sprlntf ( temp,  '[0] [Cannot  load  file  9(6  {Exiting  ...]  [OK]”,  rflle) 
fornujalort(l,  temp);  show  alert  box 

return( FRLSE); 

> 

return (TRUE); 

> 

do.  rila  1 og  ( box_l  ndex ) 

UQRO  box-J.ndex; 

Function:  Display  a dialog  box  centered  on  the  screen. 

Input:  boxuaddr  » index  of  dialog  box 

Output:  Returns  index  of  object  used  for  exit. 

«««  ««««««««  »«««««««  ««««««««  ««««»««««  ««/ 

{ 
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Listing  12-1  (continued) 

UORO  xbox,  ybox,  hbox,  ubox; 

UORD  smallx,  smally,  smallu,  smailh; 

UORD  exit^bject; 

OBJECT  *box-jaddr; 

get  address  of  box 

rsrc^addr(0,  box^index,  &box_jaddr); 

get  size  and  location  of  a box  centered  on  screen 
form-jcenter(box^ddr,  &xbox,  &ybox,  &ubox,  &hbox); 
smallx  = xbox  + (wbox  / 2); 
smally  = ybox  + (hbox  ^ 2); 
smallu  = 0; 
smailh  =0; 

reserve  area  on  screen  for  box  display 
form-jdlal  (FMD-STRRT, 

stnallx,  smally,  smallw,  smailh, 
xbox,  ybox,  ubox,  hbox); 

draw  an  expanding  box 
form«dlal(FMDJSROU, 

smallx,  smally,  smallu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

drau  dialog  box 

objc-jdrau(box_jaddr,  0,  10,  xbox,  ybox,  ubox,  hbox) 

handle  dialog  Input 

exlt-obJect  = formLjdo(box-jaddr,  0); 

drau  a shrinking  box 
f orm_dla  1 ( FMD SHRINK , 

smallx,  smally,  smallu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

reserve  area  on  screen  for  box  display 
form-jdlal  (FMD-J'INISH, 

smallx,  smally,  smallu,  smailh, 
xbox,  ybox,  ubox,  hbox); 

reset  exit  object  state  to  unselected 
box«addr[exlt_obJect) .ob«state  = NORMRL; 

return(exlt-object) ; 


set^llp(x,  y,  u,  h) 
UORD  X,  y,  u,  h; 
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Listing  12-1  (continued) 

Function:  Set  the  clipping  rectangle. 

Input:  X = X coord  of  clip  rect 

y = y coord  of  clip  rect 
u = width  (In  pixels)  of  clip  rect 
h = height  (In  pixels)  of  clip  rect 
Output:  None.  Sets  new  clipping  rectangle. 

< 

UORD  cllp[4]; 

cUp[0]  = x; 

cUp[l)  = y; 

cllp[2]  = X ♦ w - 1; 

cllp[3]  = y + h - 1; 

vs_cllp(screerL.uhandle«  TRUE,  clip); 

) 

lnlt.jdlndous( ) 

Function:  Initialize  global  window  values. 

Input:  None. 

Output:  None.  Sets  global  window  values. 

{ 

Int  1; 

num-jwlndous  = 0;  no  windows  open 

for  (1  = 0;  1 < MftX«WINDOW;  1++) 

wlndous[ 1 ] .handle  = -1;  sot  records  to  unused 
desk top. handle  = 0;  desktop  Is  always  0 

got  desktop  work  area  »/ 
ulnd_gat(desktop. handle,  WFJJORKXYUH, 

&xdesk,  &ydesk,  &udesk,  &hdesk); 
return; 

> 

create-ulndou(newklnd,  utltle) 

UORD  neuklnd; 

char  ^utltle; 

Function:  Open  a new  window. 

Input:  neuklnd  = window  attributes  to  Include 

utltle  = string  for  window  title 
Output:  Returns  Index  If  window  created,  else  -1 

Notes;  Info  line,  and  slider  values  are  NOT  set 

by  this  function.  Full  window  size  Is  set  to 
desktop  work  area. 

{ 

UORD  new; 
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Listing  12-1  (continued) 

check  If  uindows  are  available 

If  (nutTLjdlndows  >=  nRX^INDQU)  max  ulndoue  In  use 

{ 

forrTLjalert(l,  " [0]  [Maximum  number  of  uindous  reached.  ] [OK] ') ; 
return[ -1) ; 

> 

find  uindou  record  to  use 

for(neu  = 0;  neu  < Mf=)X_MlNDQUl;  neu^*!-) 

if  [uindou[neu] .handle  < 0>  record  found  ^ 

break; 

if  <neu  >=  MnK_l*JINDOU)  no  records  available 

{ 

fornLjalert(l,  "[0][No  ulndou  records  found  available. ] [OK] ; 
return[ -1) ; 

> 

create  ulndou  for  RES 
uindous [neu] .handle  = 

uincLxreate(neukind,  xdesk,  ydesk,  udssk,  hdesk); 

if  (uindous[neu] .handle  < 0)  RES  could  not  make  ulndou 

{ 

form^lert(l,  *[0][RES  error  opening  a ulndou.  (Cannot  continue.  ] [OK] ' ) 
return(-l); 

> 

fill  ulndou  record 
ulndous[neu] . type  = neuklnd; 
uindous[neu] . fullslze  = FRLSE; 
ulndous[neu] .visible  = FRLSE; 

set  ulndou  title 

uind_set (uindous[ neu] .handle « UF-NRME,  utitle,  0«  0); 

num_ulndous++;  add  ulndou  to  count 

return(neu);  return  Index 

> 

open.jjindou  [ ui_lndex ) 

Function:  Make  a ulndou  visible. 

Input:  ui_index  = Index  to  ulndou 

Output:  None.  Sets  uork  area  and  visibility  flag  In  ulndou  record. 

{ 

UORD  xsize,  ysize«  usize,  hsize; 

check  If  already  open 

if  [ulndous[ui^index] .visible) 
return; 
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Listing  12-1  (continued) 

get  current  window  size 

wincLjget ( windows [wi— index] .handie«  UF-PREVXVUH, 

&xsize,  &ysize,  &wsize,  &heize); 

if  no  size,  then  must  be  first  time  opened 
if  ( !(xsize  II  yeize  ||  wsize  ||  hsize)  ) 

{ 

xsize  s xdesk;  default  to  desktop  work  area 

ysize  s ydesk; 
wsize  = udesk; 
hsize  = hdesk; 

} 

/*  open  window 

hidB_mou5B( ) ; 

graf^roubox(  (xsize  ^ usize^Z),  (ysize  't*  hsize/2) , 
gr^box,  gr^box«  xeize,  yeize,  wsize,  hsize): 
uincLjopen(uindow8[ui^ndex] .handle,  xsize,  ysize,  wsize,  hsize); 
windows[wi^index] .uisibie  » TRUE;  flag  window  is  open 
8hou^ouse( ) ; 

) 

close-window ( wi^index ) 
function:  Close  a window. 

Input:  ui.indsx  = index  to  window  to  close 

Output:  None.  Closes  window  and  set  visibility  flag. 

{ 

UORD  xsize,  ysize,  wsize,  hsize; 

check  if  already  closed 

if  ( !uindou8(ui.index] .visible) 
return; 

get  current  window  area 

uind-get(windous[ui— index] .handle,  UF-CURRXVUH, 

&xsize,  &ysize,  &usize,  &hsize); 

close  window 
hide— mouse ( ) ; 

uind-ciose(uindow8[ui.index] .handle); 
graf-shrinkbox( (xsize  + usize^2),  (ysize  + hsize/2), 
gr-ubox,  gr-hbox,  xsize,  ysize,  wsize,  hsize); 
windou8[ui-index] .visible  = FRLSE;  flag  window  as  closed 
show-mouse ( ) ; 

dei-window(wi— index) 

UORD  ui—index; 

Function:  Delete  window  from  RES 
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Llsttng  12-1  (contiiiued) 

Input:  ul^index  = index  of  windou  to  delete 

Output:  None.  Uindou  deleted  from  RES  and  ulndous* 

{ 

If  (ulndows[ul^ndex]  .ulslbie)  still  on  screen 

close^lndou(wl^ndex) ; so  close  It 

y*  delete  from  RES 

ulndLjdelete(ulndous[ul^ndex]  .handle) ; 
set  record  as  av/allable  *y 

ulndous[ul_lndex] .handle  = -1; 
y*  remove  ulndou  from  count  *y 
nunuMlndous--; 

> 

find— ulndou (ul_handle) 

MDRD  ul-handle; 

Function:  Find  Index  for  ulndou  record  ulth  given  handle. 

Input:  ul-handle  = handle  of  ulndou  to  search  for 

Output:  Returns  Index  or  -1  If  not  found. 

{ 

register  int  1; 

for  (1  = 0;  1 < MflX-WINDQW;  1++) 

If  (uindous[ 1 ] .handle  ==  ul-handle) 
return ( 1 ) ; 
return( -1) ; 

> 

do_redrau(ul— Index,  ul_ redrau,  x,  y,  u,  h) 

UORD  ul— Index, 

(*fui-redrau)  ( ) , 

X,  y,  u,  h; 

Function:  Redrau  all  clipping  rectangles. 

Input:  ul— Index  = Index  to  ulndou  being  updated 

ul— redrau  = address  of  function  used  to  drau  ulndou 
X,  y = redrau  area  X,V  coord 

u,  h = redrau  area  uldth  and  height 

Output:  None.  Screen  Is  updated. 

Notes:  ul— redrau  cannot  use  any  parameters  or  return  any  values. 

Vou  may  create  a do— redrau  function  for  each  ulndou, 
or  pass  the  parameters  through  global  variables. 

< 

GREET  redrau,  y*  redrau  area  *y 

clip;  current  clip  area  *y 

hlde_mouse( ) ; 

ulnd-update(TRUE) ; y*  freeze  ulndou  status  *y 
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redraw. g_j<  = x;  sot  redraw  area 

redraw.g-y  = y; 
redraw. g_w  = u; 
redraw. g_h  = h; 

y*  get  first  clip  rectangle 

wlnd-get( windows [ui^ndex]  .handle,  WF_riRSTXYWH, 

&ciip.g_x,  &ciip.g.jy,  &ciip.g_w,  &ciip.g_h); 

begin  redraw  loop  until  no  more  clip  rectangles 
while  (clip.g^  &&  clip.g-h) 

< 

If  (rc_intersect(&redrau,  &cllp)) 

< 

set^iip(clip.g_x,  clip.g-jy,  clip.g^,  clip.g_Ji); 
(•wiredraw) 0 ; particular  redraw  function 

> 

wincL-get ( windows [wi^index] .handle,  UF^EXTXVt4H, 
&clip.g^,  &clip.g-y,  &clip.g_w,  &clip.g.Ji); 

> 

wlndULipdate( FALSE ) ; screen  is  ready 

show_mouse( ) ; 

) 

Application  Functions 


draw...function( ) 

Function:  Draw  in  current  window. 

Input:  None.  cur_window  is  index  to  current  window  to  draw  in. 

Output:  None.  Draws  in  window. 

< 

NQRD  temp[<t]; 

UORD  xwork,  yuork,  wuork,  huork; 

uind-get(windows[cur^indow]  .handle,  UF_UORKXYUH, 

&xuork,  &yuork,  &wuork,  &hwork); 
v/sf_interior(screen.vhandle,  2); 
v/sf^tyle(screen_vhandle,  8); 
v/sf^oiar(5creen_vhandle,  0); 
temp(0]  = xwork; 
temp(l]  = ywork; 
temp[2]  = temp[0]  wuork  - 1; 
temp[3]  s temp[l]  d-  hwork  - 1; 

vJ3ar(screen_.vyhandle,  temp];  clear  work  area 

if  (cur_window  ==  windl] 

v/sf^tyie(screerL.vhandie,  9); 
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else  if  (cur^indau  »=  uind2) 

v8f^tyie(ecreerL.vhandle,  10); 
else  if  (cur^indou  ulnd3) 

V8f^tyle(8creea.vhandle,  11); 
else  if  (cur^lndow  ss  ulnd4) 

V8f^tyle(8creen^v;handle,  12) ; 
V8f-color(8creea^s;handle,  1); 

v^liip8a(8creeruvhandl8,  xwork  + uwork/2,  ywork  + huork^2, 
uwork/2,  hwork/2) ; 
return; 

> 

control ( ) 

Function:  Master  control  function. 

Input:  None.  Program  initialization  must  be  done  before 

entering  this  function. 

Output:  None.  Returns  for  normal  program  termination. 

{ 


OBJECT 

^menuuaddr; 

address  for  menu 

UORD 

endLprogram  = FALSE; 

exit  flag 

UORD 

mevx,  mevy, 

butstate, 

meubut. 

evnt^jnulti  parameters 

keystate, 

keycoda, 

mbreturn, 

msgJ3uf(8]; 

message  buffer 

UORO 

euent. 

evnt.jnuiti  result 

meniuindex; 

keyboard  menu  title  selected 

UORD 

drauL.function( ) ; 

screen  drawing  function 

initialize  window  indices 

uindl  = -1; 
uind2  = -1; 
ulnd3  = -1; 
uind4  = -1; 

get  address  of  menu 

rsr(xjgaddr(0,  MRINMENU«  &menuL.addr) ; 

display  menu  bar 

menuL-ba  r ( menu^ddr , TRUE ) ; 

initial  button  status  to  uait  for 
butstate  = TRUE;  button  down 

uait  for  a message  Indicating  a menu  eeiectlon 
do  y*  continue  loop  until  quit 

{ 
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Listing  12-1  (continued) 

event  = Bvnt_multl(  (MU_KEVBD  | MU_NESftG  | MLLBUTTON), 

0, 

0. 

butstat0« 

0, 

0,  0, 

0,  0, 

0, 

0.  0, 

0,  0. 

msgJbuf « 

0.  0, 

&m0v;x,  &mev/y, 

&m0v;but, 

&keystate, 

&k0ycod0, 

&mbreturn) ; 

u)  i ndUupda  t0  ( TRUE ) ; 

if  (0v/ent  & nULMESRG) 

{ 

sui tch ( msg_buf [ 0 ] ) 

{ 

cas0  MhL^ELECTED:  manu  chosan 

8uitch(msg-j3uf  [4] ) 

QUIT:  0x1 t program 

and-program  = TRUE;  sat  exit  flag 

break; 

INFO:  y*  display  program  info 

doudiaiog(INFOBOX); 
break; 

UINOl:  y*  open^'close  uindou  1 *y 

if  (uindl  < 0)  y*  uindou  must  be  created  ^y 

{ 

uindl  s creata^indou( 

( NRME I CLOSER | FULLER | MOVER | SIZER ) , 

" Uindou  1 * ] ; 

if  (uindl  < 0)  y*  error  creating  uindou 

< 

end-program  = TRUE; 
break; 

> 

> 

if  (uindous[uindl] .uisibie] 

{ y*  uindou  is  open  so  close  it 

cioseLJ4indou(uindl] ; 

menu_text(menuLjaddr,  UIN01«  " Open  Uindou  1"); 

> 


< 

case 


case 


case 


y*  It  mouse  clicks  *y 
y*  mouse  buttons  of  interest  ^y 
y*  button  state  *y 
y^  first  rectangle  flags 
y*  x,y  of  1st  rectangle 
y*  height,  uldht  of  1st  rect  *y 
second  rectand  flags  *y 
y^  x,y  of  2nd  rect  *y 
y^  u,h  of  2nd  rect 
y^  message  buffer  ^y 
y*  iou,  high  uords  for  timer 
y*  x,y  of  mouse  event  *y 
y*  button  state  at  event  ^y 
y^  status  of  keyboard  at  event  *y 
y*  keyboard  code  for  key  pressed  *y 
y*  It  times  mouse  key  enter  state  *y 

y*  hold  uindou  processing  *y 
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Li8tiiigl2-1  (eontinited) 

else 

{ uindou  is  closed  so  open  it  •z' 

cpen^indou(tjindl) ; 

meRU_text(fflenLLjaddr,  UINOl,  * Close  Uindou  1*); 

> 

break; 

case  UIN02:  open/closa  uindou  2 

if  (uind2  < 0)  uindou  must  be  created 

uind2  s create^indou( 

( NRME I CLOSER | FULLER | MOVER | SIZER ) , 

' Uindou  2 '); 

if  (ulnd2  < 0)  error  creating  uindou 

< 

end-program  = TRUE; 
break; 

> 

> 

if  (uindous[uind2) .visible) 

( z'*  uindou  is  open  so  close  it 

closB-uindou(uind2) ; 

menu-text (mentuaddr,  UIN02,  * Open  Uindou  2*); 

> 

else 

{ uindou  is  closed  so  open  it 

open_uindou(uind2) ; 

fflenuL.text(menu-addr,  UIN02«  * Close  Uindou  2*); 

> 

break; 

case  UIND3:  open^ciose  uindou  3 

if  (uind3  < 0)  y*  uindou  must  be  created 

< 

uind3  = crBateuuindou( 

( NRME 1 CLOSER | FULLER | MOVER | S IZER ) , 

" Uindou  3 * ) ; 

if  (uind3  < 0)  error  creating  uindou 

< 

end-program  s TRUE; 
break; 

> 

> 

if  (uindous[uind3] .visible) 

{ uindou  is  open  so  close  it 

close-uindou(uind3) ; 

menu— text (menu-addr,  UIND3,  " Open  Uindou  3*); 

> 

else 

{ uindou  is  closed  so  open  it 

open-uindou(uind3) ; 

menu— text (menuuaddr,  UIND3.  * Close  Uindou  3*); 

> 

break; 


Windows  on  the  World  335 


Listing  12-1  (continued) 

case  UIND4:  open^close  ulndou  1 

if  (ulnd4  < 0)  ulndou  must  be  created 

< 

uind4  = createu«)indou( 

(NRME 1 CLOSER | FULLER | MOVER | SIZER ) , 

" Ulndou  4 

if  (ulnd^  < 0)  error  creating  ulndou 

< 

endLprogram  = TRUE; 
break; 

) 

> 

if  (uindou8[uind4] .visible) 

{ y*  ulndou  is  open  so  close  it 

ciose.juindou(uind4) ; 

fflenu.text((nenojaddr,  UIND4,  * Open  Ulndou  4*); 

) 

else 

{ ulndou  is  closed  so  open  it 

opBn_uindou(uind4) ; 

menu— text (menu-jaddr,  UIND4,  " Close  Ulndou  4”); 

) 

break; 

default: 

break; 

> 

reset  menu  title 

menu— tnormal(menLLjaddr,  msg-buf[3]«  1); 

menu-bar (menuuaddr,  TRUE); 

break;  /*  end  MN_SELECTED 

case  UM-REDRRU:  redrau  ulndous 

if  ( (curuulndou  = flnd-ulndou[msg-buf [3] ) ) < 0) 
break;  z'*  no  ulndou  listed 

do— redrau (cur-ulndou , drau^functlon, 

msgJbuf[4],  msg-buf[5],  msg-buf[6),  msg-buf[7]); 
break; 

case  UM-NEUTOP:  neu  ulndou  Is  on  top 

case  UM— TOPPED: 

if  ( (cur-ulndou  = f lnd_julndou(msg-buf  [3] ) ) < 0) 
break;  no  ulndou  listed 

ulnd_sst(ulndous[ cur-ulndou] .handle,  UF— TOP,  0,  0,  0,  0); 
break; 


case  UM-CLOSED:  close  box  pressed 

If  ( (cur-ulndcu  = flncLadlndou(m8g_buf [3] ) ) < 0) 
break;  no  ulndou  listed 

close-ulndou(curuulndou) ; 

If  (cur-ulndou  ~~  ulndl)  y*  set  appropriate  menu  Item 
menu— text (menu-addr,  UINDl,  ” Open  Ulndou  1"); 
else  If  (cur-ulndou  ulnd2) 
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Listing  12-1  (continued) 

menu^text((RenLi_addr,  WIND2,  “ Open  Window  2“); 
else  if  {curUAiindow  ==  wind3) 

menu-text (menu-addr,  WIND3,  * Open  Window  3*); 
else  if  (cur-wlndow  ==  wind4) 

menu-text (menu_addr,  WIND4,  " Open  Window  4'); 
break; 

case  WM-FULLED:  full  box  pressed 

if  ( (cur^indou  = f ind_uindow(msgJbuf  [3] ) ) < 0) 
break;  no  window  listed  *>' 

if  (windows [cur^indow ] .fuiisize) 

{ full  to  regular  size 

WORD  newx,  newy,  neww,  newh; 

get  previous  window  size 

w i ndLge  t ( w i ndows [ cu r-w i ndow ] . handl e , WF_PRE VXYWH , 
&newx,  &newy,  &neww,  &nswh); 
wind^et(uindows[cur-window]  .handle,  WFJCURRXYWH, 
newx,  newy,  newu,  newh); 

> 

else 

{ regular  to  full  size 

WORD  xfuii,  yfuil,  wfuii,  hfuli; 

get  full  window  size 

wincLget(windou8(cur-window] .handle,  UF-FULLXVUH, 
&xfuii,  &yfuil,  &wfuii,  &hfuil); 
u ind_se  t ( wi ndows [ cu  r-wi ndow ) • hand! e , WF JCURRXVWH , 
xfuii,  yfuil,  wfuil,  hfuil); 

> 

windou8[cur_uindow].fullsize  TRUE; 
break; 

case  Wtl-BRROWED;  arrow  and  slide  bars  not  used 

case  WM-HSLID; 
case  WM— V5L1D: 
break; 

case  WM-J5IZED:  window  resized  or  moved 

case  WM-MOVED: 

if  ( (cwr-window  ^ f ind-jwindow(m8g-buf  [3] ) ) < 0) 
break;  window  not  listed 

if  (msg_buf[6]  < WMIN-WIDTH) 
msgjauf[6]  = WMIN-WIDTH; 
if  (msgJbuf[7]  < WMIN-HEIGHT) 
msg-buf(7]  = WMIN-HEIGHT; 
windLj5et(uindou8[cur-ulndou] .handle,  WF_CURRXVWH, 

msg_buf[4],  msg-buf[5],  msg-fauf[6],  msg-buf[7]); 
break; 

default: 
break; 

> 

> 


end  message  switch 
end  message  handler 
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Lfating  12-1  (contlniied) 

if  (event  & MUJ<evBD) 

eultchCkeycode) 

{ 

caee  QUIT^EV: 

menu_index  s FILE; 

Rienu— tnormaiCmenuuBddr,  menu_lndex,  0); 

end-program  s TRUE; 

break; 

default: 

break; 

> 

menu.tnormal(menu-addr»  menu-index,  1); 
menu-bar (menuL-addr,  TRUE); 

) end  keyboard  handler 


if  (event  & MU-BUTTON) 

{ 

butstate  s !(butstate); 

> 

if  (end— program) 

( 

Int  1; 


button  handier 

end  button  handier 

close  open  uindous 
and  delete  ail  uindous 


> 


for  (1  = 0;  1 < MAX-WINDDW;  i++) 
if  (uindou8(i] .handle  >=  0) 
dei-uindou(i) ; 


uincLjupdate(rRL5E ) ; 

) uhiie  ( I end-program ) ; 

return; 

> 


/*  resume  processing 
program  control  loop 

end  function 


Main  Program 


main( ) 

< 

Initialize  GEM  Recess 


ap— id  = appi— init() 
if  (ap-id  < 0) 


Initialize  RES  routines 
no  calls  can  be  made  to  RES 
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Listing  12>1  (continned) 

{ use  GEMDOS 

Cconus( Initialization  Error.  <<HH^\n*); 

Cconus( 'Press  any  key  to  continue. ^n” ) ; 

CraucinO; 

exit(-l);  set  exit  value  to  show  error  »/ 

} 

6creen_phandle  = Got  handle  for  screen 

graf_handie(&gr_wchar,  &gr^char,  &gr^box,  &gr_hbox); 
8creen_vhandie  = operL.vuork(screen_phandie) ; 
set.^creen.jattr( ) ; Get  screen  attributes 

Rppllcatlon  Specific  Routines 


if  (!  load-resource ( "UINDQNl.RSC*  )i)o  resource  file  loaded 
exi t(l) ; 
init_uindous( ) ; 
gr a f -mouse ( PRRQU , 0x9L ) ; 
control ( ) ; 

Program  Clean-up  and  Exit 


rsrc— free[ ) ; 

v_jci8vuk(8creen-vhandle) ; close  workstation 

appl-exitO;  y*  end  program  *y 

) 


The  ^tem  header  flies  have  not  changed.  The  GEM  application 
overhead  contains  the  usual  VDI  declarations.  Note  that  the  variables 
gr_wchar,  gr-hchar,  gr-wbox,  and  gr-hboz  have  been  moved  from 
function  main( ) to  this  section  of  the  program.  The  variable  gr_wchar 
has  the  value  of  the  width  of  one  character  cell  In  pixels.  The  variable 
gr-hchar  contains  the  height  of  one  character  c^  in  pixels.  These 
values  are  used  in  the  next  two  ^define  statements  for  the  minimum 
window  width,  WMIN-WIDTH,  and  minimum  window  height, 
WMIN-HEIGHT.  The  minimum  width  will  be  at  least  two  characters 
and  the  minimum  height  will  be  at  least  three  characters.  Variable 
ap_ld  has  also  been  moved  to  the  GEM  ^plication  overhead  because 
if  the  program  needs  to  send  a message,  element  1 of  the  message 
buffer  must  contain  the  ID  number  of  the  application  originating  the 
message.  The  remainder  of  the  GEM  application  overhead  is  used  to 
facilitate  the  windows  array  mentioned  above. 


Windows  on  the  World  339 


The  use  of  the  windows  array  in  your  application  program  Is 
optional.  It  Is  used  here  because  it  is  one  of  the  most  straightforward 
and  simplest  methods  for  maintaining  multiple  windows  in  an  ap- 
plication. These  declarations  have  been  placed  under  the  GEM  ap- 
plication overhead  section  in  case  you  decide  to  use  WINDOWl  or 
WINDOW2  as  an  outline  for  your  own  applications. 

The  variable  mun-windows  keeps  track  of  how  many  windows  have 
been  opened  by  the  application.  Variable  cuT.window  is  the  index 
into  the  array  windows  for  the  currently  open  window.  Next  comes 
the  definition  of  the  WINDOW  structure.  The  constant  MAX-WINDOW 
determines  the  maximum  number  of  windows  that  may  be  created 
by  this  program  at  aaiy  one  time.  GEM  provides  for  only  eight  win- 
dows. This  program  allows  up  to  four  windows  to  be  created.  The 
array  windows  is  then  declared  as  an  array  of  WINDOW  structures. 
Variable  desktop  is  a WINDOW  structure  that  keeps  track  of  the 
desktop  window.  This  is  done  so  that  accessing  the  desktop  window 
remains  consistent  with  accessing  the  other  windows  within  the 
program.  The  four  variables  zdesk,  yde^  wdesk,  and  hdesk  hold  the 
work  area  of  the  desktop  window.  The  desktop  work  area  is  the  gray 
portion  of  the  screen  below  the  menu  bar.  In  general,  windows  should 
not  be  placed  outside  of  the  desktop  work  area  and  their  size  should 
not  exc^  the  size  of  this  area. 

Moving  to  the  GEM-related  functions,  the  first  several  functions  have 
already  been  discussed.  These  eire;  open-vwork(),  set_screen_attr( ), 
hlde-moiise( ),  show_mouse(),  load_resouTce(),  and  do_dialog().  The 
next  function,  set-clip(),  provides  an  interface  between  the  AES 
rectangle  and  the  VDI  rectangle.  To  set  the  dipping  rectangle,  the  VDI 
v8-clip( ) function  must  be  used.  However,  most  of  the  coordinates  for 
rectangular  areas  are  in  the  AES  format  consisting  of  the  coordinates 
for  the  upper  left  comer,  the  width,  and  the  height.  These  values  need 
to  be  converted  to  the  VDI  rectangle  format  consisting  of  the  coordi- 
nates for  opposite  comers.  Function  set_clip( ) provides  this  interface 
and  sets  the  clipping  rectangle. 

The  function  init_windows( ) initializes  the  windows  array  Etnd  gets 
the  values  of  the  desktop  window.  Function  init_windows( ) should 
be  called  during  the  initialization  process  of  the  program  as  in  the 
call  to  set-screen_attr( ) in  function  main().  The  init_wlndows( ) 
function  sets  the  number  of  windows  in  use  to  0 (since  no  windows 
have  been  created  yet)  and  sets  the  hemdle  for  each  window  in  the 
windows  array  to  —1.  Any  window  created  by  the  AES  has  a positive 
handle.  Setting  the  handle  to  —1  indicates  that  this  element  in  the 
windows  array  is  not  being  used.  The  desktop  window  handle  is 
initialized  to  0.  To  set  the  remaining  desktop  window  values, 
init_windows( ) makes  a call  to  wind_get( ).  The  first  parameter  of 
wind_get( ) is  the  handle  of  the  window  being  queried.  The  second 
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parameter  is  a constant  value  that  Indicates  the  type  of  information 
being  requested.  The  constant  names  and  values  are  listed  in  /^pen- 
dlx  A.  The  next  four  parameters  are  used  to  hold  the  returned  vEdues. 
In  this  call  to  wind_get( ).  the  program  is  requesting  the  size  and 
location  of  the  desktop  work  area. 

The  next  four  functions  in  this  section  of  the  program  are 
create-windowf ).  opoi-wiiidow( ).  dose-windowf ).  and  del_window( ). 
These  functions  maintain  the  windows  array  and  provide  the  ap- 
propriate procedures  for  doing  the  described  action.  Much  like  access- 
ing an  object  in  a tree. array,  your  program  is  accessing  windows 
through  the  windows  array.  Function  createL.window( ) creates  a 
window  in  the  AES  if  there  is  room.  If  not,  an  alert  box  is  issued  to 
the  user  and  the  function  returns.  The  create_window( ) function 
returns  the  index  of  the  array  element  for  the  window  created.  If  the 
window  is  not  created,  a —1  is  returned.  Just  as  an  object  is  accessed 
through  an  index,  a window  is  also  accessed  through  an  index. 

The  create_window( ) function  first  checks  if  the  maximum  num- 
ber of  windows  are  in  use.  Then  the  function  tries  to  locate  an 
element  in  the  windows  array  not  currently  in  use.  An  element  not  in 
use  is  indicated  by  a handle  element  less  than  0 (usually  —1).  Variable 
new  is  set  to  the  index  of  the  array  that  holds  the  new  window.  If  new 
exceeds  the  value  MAX-WINDOW,  there  is  a problem  in  the  windows 
array  and  an  alert  message  is  given.  If  new  contains  the  proper 
index,  a window  can  be  created.  Function  wlnd-cteate( ) is  called  and 
returns  a handle  to  the  newly  created  window.  The  first  parameter  to 
wlnd-create( ) specifies  the  control  areas  to  include  in  the  window. 
The  next  four  parameters  define  the  largest  size  that  the  window  may 
assume.  Because  a window’s  size  may  not  exceed  the  desktop  work 
area,  the  largest  size  assumed  in  this  program  is  the  entire  desktop 
work  area  If  the  calling  program  needs  a smaller  full-size  window,  the 
full-size  window  area  can  be  set  through  the  wind_set( ) function.  The 
values  used  for  wlnd-cieate( ) onfy  limit  the  absolute  maximum  size 
that  the  window  may  achieve.  Function  wind_czeate( ) returns  the 
handle  of  the  new  window.  If  the  handle  returned  is  less  than  0,  the 
AES  had  a problem  creating  the  window  and  an  alert  box  indicates 
the  situation. 

The  element  in  the  windows  array  is  then  filled.  The  type  field  is 
set  to  the  attributes  of  the  window.  The  full-size  field  starts  at  FALSE. 
The  visible  field  Is  also  set  to  FALSE  because  creating  a window  does 
not  open  the  window.  Opening  a window  must  be  done  explicitly.  Next 
function  wind_set( ) is  called  to  set  the  title  bar  of  the  window.  Finalfy, 
variable  nnm-wlndows  is  incremented  1 so  that  the  window  count 

is  accurate.  The  index  to  the  nevefy  created  window  is  returned  to  the 
calling  program. 

Function  open-window( ) takes  the  index  of  a window  and  opens 
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that  window.  The  process  of  opening  a window  simpty  requires  a call 
to  function  wind-open( ).  However,  to  make  a program  look  more 
sophisticated,  opening  a window  should  consist  of  hiding  the  mouse 
(to  avoid  any  screen  drawing  conflicts),  drawing  a growing  box  out- 
line. opening  the  window,  and  showing  the  mouse.  Function 
opeii-vkndow( ) can  be  called  at  any  time  after  a window  has  been 
created  but  should  not  be  called  when  the  window  is  already  open. 
Therefore,  the  first  statement  in  open-windowf ) tests  if  the  window 
is  visible.  If  it  is.  the  function  just  returns.  If  not  open_windoiw( ) 
continues  the  ojjenlng  process. 

Two  conditions  can  occur  when  a window  is  opened.  Either  the 
window  has  never  been  opened  before  or  it  is  being  reopened.  In  the 
latter  case,  it  would  make  sense  that  the  window  be  opened  to  the 
same  size  it  was  when  it  was  closed.  A program  can  request  the 
previous  size  of  a window  through  the  wind_get( ) function  shown  in 
<q>eiiL.window( ).  The  constant  WF_PREJVXYWH  Indicates  that  the 
previous  position  and  size  of  the  window  are  desired.  Tlie  information 
is  returned  into  variables  xsize,  ysize,  wsize,  and  hsize.  If  the  window 
has  never  been  opened  before,  these  variables  all  have  the  value  of  O. 
The  next  statement  in  open_window( ) tests  for  this  condition.  If  the 
window  has  never  been  opened  before,  its  defatilt  starting  size  is  the 
size  of  the  desktop  vrork  area.  If  a previous  size  is  avail^Ie.  these 
values  are  used.  To  actually  open  the  window,  function  hlde-mousef ) 
is  called  followed  the  gra£-growboz( ) function.  Next  the  window  is 

opened  through  wlnd.uqieii()  and  the  mouse  is  redispla}^  with 
show-moiisef ). 

Function  Idde-motisen  is  called  before  processing  the  screen  to 
avoid  conflicts  with  the  screen  manager.  When  the  mouse  is  drawn, 
the  image  under  the  mouse  is  saved  in  memoiy.  When  the  mouse  is 
moved,  the  screen  manager  replaces  this  image.  If  hide-monsef ) is 
not  called,  when  the  mouse  is  moved,  the  screen  manager  replaces  the 
contents  of  the  screen  under  the  mouse  before  the  window  was 
drawn.  You  have  probabty  noticed  this  situation  in  some  of  the  earlier 
programs  where  the  screen  was  cleared  to  a white  background,  and 
when  the  mouse  was  moved  a small  rectangular  patch  of  gray  Avas 
drawn  in  its  place.  Turning  off  the  mouse  causes  the  screen  manager 
to  reset  the  saved  image. 

The  next  function,  dose-wlttdowf ).  closes  a window.  If  the  window 
is  already  closed,  the  function  returns.  Hie  first  function  call  is  to 
wind_get( ) to  get  the  current  position  and  size  of  the  window  (using 
the  constant  WF_CURRXYWH).  These  values  are  used  by  the 
graf-dirinkboixf ) function.  To  dose  the  window,  faide-monsef ) is 
called  first  the  shrinking  outline  box  is  drawn,  the  window  is  dosed, 
the  visible  flag  is  set  to  FALSE,  and  dtow_jnou8e( ) is  called. 

Ddetlng  a window  in  del_wlndow( ) is  even  easier  than  dosing  a 
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window.  The  first  statement  here  checks  if  the  window  is  currentty 
visible  on  the  screen.  If  it  is,  the  window  needs  to  be  closed  before  it 
can  be  deleted  from  the  AES.  If  the  window  were  deleted  from  the  AES 
before  being  erased  from  the  screen,  the  onfy  way  to  remove  the 
window’s  image  would  be  to  erase  the  entire  screen  emd  redraw  all 
the  open  windows.  To  avoid  this  problem,  if  the  window  is  still  visible 
deL_window( ) calls  <do8e-window( ) before  continuing.  Once  the  win- 
dow is  closed,  it  can  be  removed  from  the  AES  with  the  wind-deletef ) 
ftmctlon.  Next  the  handle  for  the  element  in  the  windows  array  is  set 
to  —1  to  Indicate  that  this  array  element  is  now  available  again. 
Finally,  the  number  of  windows  in  use  Is  decremented  1. 

There  is  one  other  function  needed  to  utilize  the  windows  array. 
The  AES  refers  to  a window  by  its  handle.  When  using  the  windows 
array,  a window  is  referenced  by  its  index.  Therefore,  an  £q>pllcatlon 
needs  a function  to  find  which  element  in  the  Mdndows  array  has  the 
specified  handle.  Function  find-wlndowsf ) does  this  search.  Given 
the  handle  for  a window,  it  searches  throu^  the  windows  array  and 
returns  the  index  to  the  windows  array  for  the  element  that  has  that 
handle.  If  the  handle  is  not  found.  —1  is  returned. 

The  last  function  discussed  in  this  section  is  do-redzaw( ).  This 
function  is  called  whenever  the  program  receives  a window  redraw 
message.  E^ssentlalfy,  do-redrawf ) implements  the  redrawing  process 
discussed  earlier.  The  parameters  of  the  do_xedraw( ) function  are  the 
index  of  the  window  to  redraw,  the  address  of  the  function  that 
redraws  the  window,  and  the  redraw  area.  No  values  are  returned.  Two 
rectan^es,  called  zedzaw  and  <dip,  are  used  in  function  do-iedzaw(). 
Rectangle  redraw  corresponds  to  the  redraw  area,  passed  in  the 
parameters  z.  y.  w,  and  h.  Rectangle  dip  is  set  to  the  intersection  of 
the  visible  rectan^e  and  the  redraw  rectangle. 

Function  do_redraw( ) starts  with  a call  to  hide-mousef ) for  the 
same  reason  hide^moasef ) is  called  when  opening  and  dosing  a 
window.  Next,  wind-i^datef ) is  called  with  a parameter  of  TRUE. 
This  tells  the  AES  that  the  application  is  updating  its  windows  and 
that  it  should  not  process  any  user  interactions  with  the  screen.  This 
prevents  a backlog  of  events  from  occurring  and  ensures  that  the 
screen  remains  current  Next  the  redraw  rectangle  is  initialized. 

The  redraw  process  loops  through  all  visible  rectangles  in  a win- 
dows rectangle  list  The  first  rectangle  on  the  visible  rectan^e  list  is 
retrieved  using  wind_get()  with  constant  WFJFIRSTXYWH  in  its 
parameter  list  The  first  rectan^e  is  then  returned  into  the  next  four 
parameters.  A while  loop  processes  each  visible  rectangle.  If  the  width 
and  height  for  a visible  rectangle  are  both  0.  all  rectangles  have  been 
processed  and  the  loop  can  terminate. 

Within  the  loop,  the  first  call  is  to  function  rc-intenect( ).  This 
function  returns  TRUE  if  the  two  rectangles  in  its  parameter  list 
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intersect  with  one  another.  Otherwise  FALSE  is  returned.  If  the 
rectangles  do  intersect,  the  function  calculates  the  intersection  rec- 
tangle euid  returns  its  position  and  size  in  the  second  parameter. 
Thus,  the  second  parameter  is  changed  by  rc_  intersect! ) to  describe 
the  intersection  rectangle. 

If  the  visible  rectangle  and  the  redraw  area  do  intersect,  the  clipping 
rectan^e  is  set  to  the  intersection  and  the  window  is  redrawn.  The 
while  loop  continues  by  using  wiiid-get()  to  retrieve  the  next  rec- 
tangle in  the  window’s  visible  rectangle  list  This  call  to  wind_get( ) 
uses  the  constant  WF_NEXTXYWH. 

When  all  visible  rectangles  have  been  examined,  function 
wlnd-update( ) is  called  with  a parameter  FALSE.  This  indicates  to 
the  AEIS  that  the  screen  has  been  processed  and  that  it  should 
continue  its  window  processing.  Finalfy,  show_mouse( ) is  called  to 
return  the  mouse  to  the  screen. 

The  do-iedzaw( ) function  is  designed  to  handle  a single  entry  point 
for  redrawing  a window.  However,  the  redraw  function  used  cannot 
accept  any  parameters  from  do_zedraw( ) function  and  any  returned 
values  are  ignored.  In  most  cases,  this  is  not  a problem  as  can  be  seen 
in  this  program  and  the  next.  If  parameters  are  needed,  th^r  must  be 
used  as  ^obal  variables. 

The  window-drawing  function  is  located  in  the  application  function 
section  of  WINDOWl.  Function  dzaw_function( ) draws  an  ellipse 
inside  a window.  For  the  function  to  know  the  window  size  and  shape, 
it  calls  function  wind_get( ) to  get  the  work  area  position  and  size. 
First,  the  window  is  cleared  using  a solid  white  pattern  fill  with 
function  v_bar( ) called  to  clear  the  work  area.  The  next  step  is  to 
select  the  fill  pattern  to  use.  The  global  variable  cur_window  contains 
the  index  of  the  current  window  being  updated.  The  four  global 
variables  windl,  wind2,  winds,  and  wind4  contain  the  index  for 
window  1.  window  2,  window  3,  and  window  4,  respectively.  These 
values  are  set  when  the  window  is  created.  The  window  currently 
being  updated  selects  the  fill  pattern  to  use.  Once  the  pattern  is 
selected,  the  color  is  set  to  1 and  the  ellipse  is  drawn  to  fill  the  entire 
work  area. 

The  program  flow  for  WINDOWl  handles  more  events  than  before 
but  is  basically  in  the  same  format  Starting  with  function  main( ), 
the  initialize  GEM  access  section  is  the  same  it  has  always  been.  The 
application-specific  routines  load  the  resource  file  using  function 
load-  resource! ).  Then  init_windows! ) is  called  to  initialize  the  win- 
dows array  and  the  desktop  window  structure.  Function  gtafLmouse! ) 
is  called  to  set  the  mouse  form  to  the  arrow.  When  an  application  is 
initiated  from  the  desktop.  GEM  converts  the  mouse  form  to  a bumble 
bee  while  the  program  is  loading.  Once  the  program  is  loaded,  GEM 
passes  control  to  the  application  but  does  not  return  the  mouse  form 
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to  the  arrow  image.  Therefore,  the  application  should  set  the  mouse 
form  to  whatever  image  is  required.  The  step  in  main! ) is  to  call 
function  controU).  When  oontrolO  returns  to  mainf),  ^e  usual 
dean-up  and  exit  procedures  are  followed. 

Hie  first  thing  that  function  oontrolO  does  is  set  the  variables 
windl,  wind2,  wind3,  and  wlnd4  to  the  vdue — 1.  These  four  variables 
hold  the  Indices  for  the  four  possible  windows.  They  are  global  and 
used  by  the  drawing  function.  Next  controlf ) finds  the  address  of  the 
menu  and  displays  the  menu  bar.  The  variable  bntstate  is  set  to 
TRUE.  This  is  simply  used  to  teach  button  events.  Although  button 
events  are  not  actually  used  in  this  program,  they  are  Induded  here 
to  give  you  an  idea  as  to  how  buttons  are  handled.  Function 
evnt-multi( ) is  called  to  wait  for  a keyboard,  message,  or  button 
event  When  an  event  occurs,  it  may  indicate  that  some  kind  of 
window  processing  needs  to  be  done.  Thus,  wlnd-iqkbtie( ) is  called 
so  that  no  further  window  events  occur  imtil  this  event  has  been 
processed. 

If  the  event  is  a message  event  the  type  of  message  is  tested.  For 
menu  sdectlon  messages,  the  menu  item  is  tested.  Case  QUIT  means 
that  the  Quit  option  is  sdected,  so  variable  end-^iiogram  is  set  to 
TRUE.  Because  the  program  is  inside  two  switch  statements  and  a 
loop,  a single  break  statement  does  not  exit  the  loop.  Thus  the 
variable  end-program  is  used  as  a flag  at  the  end  of  the  loop.  If  INFO 
Is  sdected,  the  INFOBOX  dialog  box  is  drawn.  The  other  menu  selec- 
tions correspond  to  the  opening  or  closing  of  a window.  If  the  window 
is  not  visible,  the  menu  selection  reads  “Open  Window  1”  or  whatever 
window  number  is  sqppropriate.  If  the  window  is  visible,  the  menu 
sdectlon  reads  "Close  Wndow  1.” 

The  procedure  to  open  or  dose  a window  is  the  same  for  each  of 
the  four  windows.  The  first  test  in  this  case  checks  if  the  window  has 
been  created.  If  the  window  has  an  index,  it  must  exist  In  the 
windows  array.  If  the  window’s  Index  is  — 1 (the  initialized  value),  the 
window  must  be  created.  Function  create_window( ) is  called  specify- 
ing the  control  areas  to  indude  and  the  window  title.  If  the  index 
returned  Is  less  than  0,  an  error  must  have  occurred  and  the  program 
will  exit 

If  the  window  is  visible,  it  should  be  dosed.  A call  to  dose— window( ) 
doses  the  window.  Then  the  menu  text  is  changed  to  read  “Open 
Window  1,”  or  2,  3,  or  4.  If  the  window  is  not  visible  (either  it  was 
previously  dosed  or  has  just  been  created),  the  window  must  be 
opened.  Function  open-window( ) opens  the  appropriate  window,  and 
the  menu  text  Is  changed  to  indicate  that  the  window  can  be  dosed. 
At  the  end  of  the  menu  sdectlon  switch  statement  the  menu  title  is 
reset  and  the  title  Is  redrawn. 

The  next  message  case,  WM -REDRAW,  is  for  a redraw  event  The 
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redraw  event  Indicates  that  part  of  a window  work  area  must  be 
redrawn  due  to  some  user  action.  The  message  buffer  contains  the 
following  information.  Element  3 contains  the  window  handle  to  be 
redrawn.  Element  4 contains  the  x position  of  the  upper  left  comer 
of  the  redraw  area.  Oement  5 contains  the  y position  of  the  upp>er 
left  comer  of  the  redraw  area.  Elements  6 and  7 contain  the  width 
and  height  of  the  redraw  area.  All  coordinates  are  measured  in  screen 
coordinates. 

To  handle  a redraw  event  the  program  must  first  get  the  index  of 
the  window  being  processed.  Variable  cur-windkiw  is  set  to  the  index 
returned  by  flnd_.wlndow( ).  If  cur-window  is  less  than  0,  the  window 
is  not  listed  in  the  windovro  array  and  the  redraw  process  should  not 
continue.  If  the  current  window  is  found,  the  do_redraw( ) function 
is  called.  The  parameters  to  the  do_redraw()  function  Include  the 
address  of  the  window  drawing  function  and  the  position  and  size  of 
the  redraw  area. 

Messages  WM_NEWTOP  and  WMTOPPED  Indicate  that  a window 
belonging  to  this  application  has  become  the  new  top  window.  The 
current  window  is  located  and  the  wind-set( ) function  is  called  with 
parameter  WF-TOP  to  set  the  window  as  the  top  window.  The 
wind_oet( ) call  causes  the  AE^  to  issue  a redraw  command  for  the 
new  top  window.  Here,  as  in  all  of  the  messages  associated  with  the 
window,  element  3 of  the  message  buffer  contains  the  handle  of  the 
window  to  be  acted  upon. 

Case  WM_CLOSED  indicates  that  the  dose  box  has  been  pressed. 
The  index  for  the  window  to  be  dosed  is  located  and  dose-windowf ) 
is  called.  Because  the  window  has  been  dosed,  the  menu  entry  must 
be  changed  to  allow  the  user  to  reopen  this  particular  window.  By 
testing  the  current  window  index  against  the  values  in  windl,  wind2, 
winds,  and  wind4,  the  program  determines  which  menu  entry  needs 
to  be  changed. 

Case  WM_FULLED  is  a message  sent  when  the  full  box  is  pressed. 
The  cur-window  value  is  set  and  the  window  size  is  checked.  If  the 
window  is  already  at  its  full  size,  the  prc^ram  gets  the  previous 
window  size  and  changes  the  window  to  that  size.  A call  to  wind_get( ) 
with  parameter  WF-PREVXYWH  gets  the  previous  window  size.  Func- 
tion wind_set( ) is  called  with  parameter  WF-CURRXYWH  to  change 
the  window  size.  If  the  window  is  in  its  r^ular  size,  the  program  must 
make  the  window  Its  full  size.  This  is  done  by  calling  wind_get( ) with 
parameter  AVF_FULLXYWH  to  get  the  position  and  size  of  a fbll-slze 
window.  The  current  window  size  is  set  to  the  full-window  size  by 
calling  wind-set( ) with  the  parameter  WF-CURRXYWH.  The  full-size 
field  in  the  window  stmcture  is  then  togged  using  the  "=  operator. 
This  operator  does  a bit-wise  XOR  between  the  current  value  of  field 
full-size  and  TOUE.  If  full-size  is  TRUE,  TRUE  XOR  TOUE  yields 
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FALSE  so  the  value  of  full-size  is  toggled  If  full-size  is  FALSE,  FALSE 
XOR  TRUE  yields  TRUE,  which  also  toggles  full-size. 

Cases  WM-ARROWED,  WM-HSLID,  and  WM_VSLID  are  used  for 
the  arrow  and  slide  bars.  However,  this  program  does  not  provide  the 
sliders  or  arrows.  These  messages  should  not  occur  in  this  program 
so  they  are  ignored. 

Cases  WM-SIZED  and  WM-MOVED  indicate  that  the  window  has 
been  resized  or  moved.  Once  the  current  window  has  been  foimd, 
elements  6 and  7 contain  the  requested  width  and  height  of  the 
window.  These  dimensions  are  tested  against  the  minimum  values. 
Function  wind_sct( ) is  then  called  to  set  the  current  position,  width, 
and  height  of  the  window.  This  is  the  last  window  message  event 

The  next  portion  of  control! ) handles  a keyboard  event.  This 
program  has  no  keyboard  events  that  it  should  accept  so  all  keyboard 
events  are  ignored.  The  QUITJECE^  case  has  been  commented  out  so 
that  it  no  longer  functions  as  it  did  in  MENU2.  You  can  use  this  case 
as  a model  for  any  other  k^rboard  events  }rour  program  needs  to 
process.  Remember  that  for  menu  shortcuts  your  application  must 
change  the  menu  title  state  to  SELEXH'ED  dtirlng  processing  and 
NORMAL  when  processing  is  complete. 

The  last  event  handled  Is  a button  event  In  WINDOWl,  the  button 
handler  is  rather  primitive.  If  a button  down  event  occurs,  the 
program  waits  for  a button  up  event  When  the  button  up  event 
occurs,  the  program  goes  back  to  waiting  for  a button  down  event 
This  part  of  the  program  is  included  just  for  demonstration  purposes. 

The  last  part  of  control!)  checks  the  end-program  flag.  If 
end-program  is  TRUE  fthat  is,  the  end  of  the  program  has  been 
requested),  all  active  windows  are  deleted.  If  a window  has  a handle 
fmeaning  that  it  is  still  active),  deL.window! ) is  called  for  the  index 
of  that  window.  Finally,  wind-i^date! ) is  called  with  parameter 
FALSE  to  indicate  that  window  updating  may  proceed.  If  encLprogram 
is  not  TRUE,  the  while  loop  repeats  to  wait  for  another  event. 


Using  WINDOWl 

WINDOWl  lets  you  play  with  various  window  events.  The  Windows 
menu  allows  you  to  open  or  close  any  one  of  four  windows.  The 
windows  can  be  opened  and  closed  In  any  order.  If  you  have  windows 
open  on  the  screen,  you  can  dose  them  using  either  the  dose  boxes 
or  the  menu.  If  there  are  open  windows  on  the  screen  and  you  press 
the  Quit  option,  the  windows  are  automatically  dosed  before  the 
program  exits.  Try  using  the  full  box,  size  box,  and  dose  box.  Try 
using  the  move  bar  to  move  the  windows  aroimd. 

One  interesting  experiment  is  to  open  window  1 and  window  2.  Size 
each  window  down  to  about  one-quarter  of  the  work  area.  Place 
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window  1 sUghtty  below  the  top  of  the  work  area  and  slightly  In  from 
the  edge.  Move  window  2 so  that  it  covers  the  lower  right  quarter  of 
window  1.  Now  move  window  2 so  that  it  uncovers  window  1.  The 
imcovered  portion  of  window  1 is  then  redrawn.  Note  that  the  area 
that  is  uncovered  Is  redrawn  with  the  correct  pattern,  but  that  the 
pattern  does  not  line  up  with  the  rest  of  the  window  contents.  This 
demonstrates  another  problem  with  having  word-aligned  patterns  on 
the  screen.  Moving  a window  copies  the  content  of  the  work  area.  In 
this  experiment  the  content  of  the  work  area  is  copied  so  that  the 
pattern  is  no  longer  word-aligned.  To  avoid  this  problem,  you  can 
force  the  window  to  be  redrawn  when  It  is  moved  or  not  allow  the 
window  to  move  if  it  contains  a pattern. 

Another  condition  to  test  is  resizing  the  window.  When  a window 
is  resized  to  a smaller  width  and  height  the  content  of  the  work  area 
is  not  redrawn.  Onty  when  a window  is  resized  to  a larger  work  area 
is  a redraw  message  issued. 

Look  over  WINDOWl.  WINDOW2  adds  a few  more  control  areas  and 
shows  you  how  to  handle  the  data  display  in  the  work  area.  As  for 
WINEK>W1,  try  adding  a few  enhancements.  One  would  be  to  change 
open_window( ) to  allow  the  application  to  specify  an  initial  open  size. 
Another  would  be  to  specify  the  full  size  of  the  window  rather  than 
defavilting  to  the  desktop  work  area.  When  you  have  made  some 
changes  to  WINDOWl,  move  on  to  WINDOW2. 


Program  WINDOW2 

Program  WINDOW2  is  a text  file  viewing  program.  The  user  opens  a 
text  file.  This  file  is  loaded  into  memory  and  displa}^  through  the 
window.  ^ using  the  sliders  and  scroll  bars,  the  user  can  view  any 
portion  of  the  file.  Closing  the  window  clears  the  file  from  memory 
and  allows  the  user  to  open  another  file. 

This  program  combines  the  operation  of  program  LISTER  and 
program  WINDOWl.  Program  LISTER  provides  some  of  the  file-access- 
ing routines.  Program  WINDOWl  supplies  the  outline  for  a window- 
based  application.  The  first  thing  needed  before  continuing  is  a 
resource  file. 

Program  WLNDOW2  Resource  File 

WINDOWl  uses  two  object  trees  (see  Figure  12-6):  one  for  the  dialog 
box  and  one  for  the  menu.  The  dialog  box  is  named  INFOBOX.  Set 
the  menu  entries  as  shown  in  the  figure.  Again,  name  the  first  entry 
In  the  Desk  menu  as  INFO.  The  File  menu  contains  two  entries.  Open 
and  Quit  Entry  Open  is  named  OPENFILE  and  entry  Quit  is  named 
QUIT. 
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Desk  Accessory  1 
Desk  Accessory  2 
Desk  Accessory  3 
Desk  Accessory  4 
Desk  Accessory  5 
Desk  Accessory  6 


File- 


Open 

Quit 


About  UIHD0U2 


This  is  the  second  program  which 
demonstrates  the  use  of  windows. 


Figure  12-6  Program  WINDOW2  Resource  File 

WINDOW2  Layout 

The  basic  layout  of  program  WINDOW2  is  veiy  similar  to  WINDOWl. 
The  s^plication-speciflc  data  section  is  someadiat  different  Take  a 
look  at  this  section  as  shown  in  Listing  12-2. 

Listiiig  12-2  Program  W1NDOW2 

UIND01(I2.C  Sample  uindou  application  tl2 

This  program  demonstrates  the  use  of  the  slider  and  arrows 
on  a uindou. 

System  Header  riles  & Constants 


ttlnclude 

<stdlo.h> 

/« 

Standard  10 

II  Include 

<csblnd.h> 

/# 

GEMDOS  routines 

Ulnclude 

<gemdefs.h> 

/« 

GEM  AES 

It  include 

<obdefs.h> 

GEM  constants 

ttlnclude 

<errno.h> 

errno  declaration 

lldeflne 

FALSE  0 

tldeflne 

TRUE  IFRLSE 
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Lisdug  12>2  (continued) 

✓««»»»»««»«»»«««»»«««»»»»»»»»»»»»»»»»»»»«»»»»»»»»»» 

GEM  Rppllcatlon  Ov/erhead 


Declare  global  arrays  for  VDI. 
typedef  Int  WORD;  WORD  Is  16  bits 

WORD  contrl(12],  VDI  control  array 

lntOMt(120],  lntln[126],  VDI  Input  arrays 

ptsln[126],  ptsout[126];  VDI  output  arrays 


sc  r een_vhand 1 e , 

✓» 

sc  reerL4ihandl  e , 

8crean_rez, 

color^creen. 

x_max. 

y-max. 

m-hidden  = FALSE; 

✓* 

virtual  screen  uorkstatlon  »>' 
physical  screen  uorkstatlon 
screen  resolution  0,1,  or  2 
flag  if  color  monitor 
max  X screen  coord 
max  y screen  coord 
mouse  visibility  status 


WORD  gr^char,  grJichar,  values  for  system  sizes 

gr^box,  gr_hbox; 

set  min  ulndou  size 

tldeflne  WMIN-WIDTH  (2»grjdbox) 

ttdefine  WMIKLhEIGHT  (3»gr^box) 


WORD 

ap_id; 

WORD 

num_uindou8; 

WORD 

cur_ulndou; 

typedef 

struct  ulnd.type  { 

WORD 

handle; 

WORD 

typo; 

WORD 

visible; 

WORD 
> WINDOW; 

fullslze; 

Udefine 

MfiXJJINDOW  4 

WINDOW 

ulndous(MRX_WINDOW] 

WINDOW 

desktop; 

WORD 

xdesk,  ydesk, 
udesk,  hdesk; 

✓»  application  ID 

number  of  wlndous  open  *y 
Index  for  current  ulndou 

ulndou  record 
y*  RES  ulndou  handle 
>'*  ulndou  attribute  bits 
flag  If  visible 
y*  flag  If  full  size 


y*  allow  for  4 windows  *y 
y*  array  of  window  records  *y 
desktop  record  *y 
y*  desktop  area  *y 


Rppllcatlon  Specific  Data 


ttlnclude  *windaw2.h*  y*  resource  header  file  *y 


WORD  flleuln;  /»  file  ulndou  Index 
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WORD  max-jcolumn,  max^linG,  H of  cols,  lines  In  file 

wls-column,  vis-iine,  /«  tt  of  cols,  line  visible  in  window 

cur_colutnn,  cur— line,  start  col,  line  In  window 

lastcur_llne,  lastcur-column,  previous  values 
hdelta,  vdelta;  size  of  slider  movement 

WORD  xchar,  ychar;  size  of  char  cell  in  pixels 

ttdefine  MfiXjCOLUMNS  2S6  hold  256  chars/  line  »/ 

ttdeflne  KfiX-i-INES  1000  /*  hold  up  to  1000  lines 

char  *buf— llne(MflX-LINES];  /*  lines  in  buffer  »/ 

char  »blank  = •\0";  blank  line 

char  def-search[32]  = /*  default  search  path  */ 

sel-f lle[16] , file  selected 

file_name[64] ; /*  full  file  name  to  open  */ 

6E(1-related  Functions 

WORD  open— vuork(phyB-handlB) 

WORD  physJiandie; 

Function:  This  function  opens  a virtual  workstation. 

Input:  physJiandle  = physical  workstation  handle 

Output:  Returns  handle  of  workstation. 

< 

UORD  uark_ln[ll], 

work-out [ 57 ] , 

new-handle;  /*  handle  of  workstation 

Int  1 ; 

for  (1  = 0;  i < 10;  !•►•►)  /*  sot  for  default  values  */ 

work— ln[l]  » 1; 

work— ln[10]  = 2;  use  raster  coords  */ 

new-handie  » phys-handle;  use  currently  open  wkstatlon 

v-opnvwk(worl<— in,  &newiJiandle,  uork-jout); 
return(neuLJiandle) ; 

> 

BO  t-j5C  reen^a  1 1 r ( ) 

Function:  Set  global  values  about  scresn. 

Input:  None.  Uses  screen— vhandle. 

Output:  Sets  x^ax,  y-/nax,  color-screen,  and  screen— rez. 

{ 

WORD  worl<_ou  t [ 57  ] ; 
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v/q^xtnd(screen_vhandle,  0«  uork^ut); 
x^ax  = uark_out[0]; 
y_max  = uork-jout(l) ; 

QcreerL^ez  = 6etrez();  /»  0 = lau,  1 = med,  2 = high 

coior_screen  = (screen_rez  < 2);  mono  2,  color  0 or  1 

> 

hida^ouse( ) 

runction:  Make  mouse  invisible  if  currently  visible. 

Input:  None.  Uses  variable  muJiidden. 

Output:  Sets  nuhidden  to  TRUE. 

I 

if  ( 9(n_hidden) 

{ 

graf_mause(MJOrr,  0x0L); 
m-hidden  = TRUE; 

) 

> 

shou.jnou8e( ) 

Function:  Hake  mouse  visible  if  currently  invisible. 

Input:  None.  Uses  ni_hidden. 

Output:  None.  Sets  m-Jiidden  to  FRLSE. 

{ 

if  (m_hidden) 

< 

graf^ouse(MJDN,  0x0L); 
m_hidden  = FRLSE; 

> 

} 

load— resource(rf lie) 
char  *rfile; 

Function:  Load  resource  file. 

Input:  rfiie  = string  uith  resource  file  name. 

Output:  Returns  TRUE  if  file  loaded,  else  FRLSE. 

{ 

char  temp[12B); 

if  ( !r8rc_load( rfiie) ) error  loading  file 

{ set  alert  format 

sprintf ( temp,  ”[0] [Cannot  load  fils  %q  (Exiting  ...]  [OK]*,  rfiie) 
form_jalert(l,  temp);  show  alert  box 

return (FALSE) ; 
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r0turn(TRUE) ; 

> 

dCLjd  i a 1 og  ( box_index ) 

I40R0  box^ndex; 

Function:  Display  a dialog  box  centered  on  the  screen. 
Input:  box-jaddr  = index  of  dialog  box 

Output:  Returns  index  of  object  used  for  exit. 

< 

UQRD  xbox,  ybox,  hbox,  ubox; 

UDRD  smaiix,  smaily,  smaiiu,  smaiih; 

UDRD  exit^bject; 

OBJECT  *box-jaddr; 

y*  get  address  of  box 

rsrc^addr(0,  box_index,  &box_addr); 

get  size  and  location  of  a box  centered  on  screen 
form-xenter(box-Bddr,  &xbox,  &ybox,  &ubox,  &hbox); 
emallx  = xbox  + (ubox  / 2); 
smaiiy  = ybox  + (hbox  ^2); 
smailu  = 0; 
smaiih  = 0; 

reserve  area  on  screen  for  box  display 
form_jdial  (Ff1D_STftRT, 

smaiix,  smaiiy,  smailu,  smaiih, 
xbox,  ybox,  ubox,  hbox); 

drau  an  expanding  box 
fornudlai(FMDJBRDW, 

smaiix,  smaiiy,  smailu,  smaiih, 
xbox,  ybox,  ubox,  hbox); 

drau  dialog  box 

obJc^rau(box_addr,  0,  10,  xbox,  ybox,  ubox,  hbox) 

handle  dialog  input 

exit_obJect  = forriLjdo(box-^ddr,  0); 

drau  a shrinking  box  */ 
fornudial (FMD_SHRINK, 

smaiix,  smaiiy,  smailu,  smaiih, 
xbox,  ybox,  ubox,  hbox); 

reserve  area  on  screen  for  box  display 
form_dial  (Ff1D_FINISH, 

smaiix,  smaiiy,  smailu,  smaiih, 
xbox,  ybox,  ubox,  hbox); 
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reset  exit  object  state  to  unseiected 
box_addr[exit^bJect]  .ob^tate  = NQRMRL; 

return(exit_Dbject) ; 

> 

sBt-jclip(x,  y,  w,  h] 
blORD  X,  y,  u,  h; 

Function:  Set  the  clipping  rectangle. 

Input:  X = X coord  of  clip  rect 

y = y coord  of  clip  rect 
u = uidth  (in  pixels)  of  clip  rect 
h = height  (in  pixels)  of  clip  rect 
Output:  None.  Sets  neu  clipping  rectangle. 

{ 

UQRD  ciip[4]; 

clip[0]  = x; 

ciip[l]  = y; 

ciip[2]  = X + w - 1; 

ciip[3]  = y + h - 1; 

us^iip(scresn_v;handie,  TRUE,  clip); 

> 

init^indous( ) 

Function:  Initialize  global  uindou  values. 

Input:  None. 

Output:  None.  Sets  global  uindou  values. 

< 

int  i; 

nuciLJdindous  = 0;  no  uindous  open 

for  (i  = 0;  i < MflX-WlNDOW;  i++) 

uindous(i).handle  = -1;  set  records  to  unused 
desk top. handle  = 0;  desktop  is  aluays  0 

got  desktop  uork  area 
uind-jget ( desktop. handle , UF3I0RKXYUH, 

&xdesk,  &ydssk,  &udesk,  &hdesk); 
return; 

} 

create-uindou(neukind,  utitls) 

UORD  neukind; 

char  *utitle; 

Function:  Open  a neu  uindou. 
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Input:  newkind  = uindou  attributes  to  include 

utitle  = string  For  uindou  title 
Output:  Returns  index  if  uindou  created,  else  -1 

Notes:  Info  line,  and  slider  values  are  NOT  set 

by  this  function.  Tull  uindou  size  is  set  to 
desktop  uork  area. 

{ 

VIORD  neu; 

check  if  uindous  are  available 

if  (nuflujuindous  >s  MRX^INDOU)  max  uindous  in  use 

{ 

forflualert(l,  *[0] [Maximum  number  of  uindous  reached. ] [OK] ; 
return(-l); 

} 

find  uindou  record  to  use 

for  (neu  = 0;  neu  < MRX_UINDOU;  neu-i^'t’) 

if  (uindous [neu]. handle  < 0)  record  found 
break; 

if  (neu  >=  MflX-WINDOU)  no  records  available 

( 

forflLjalert(l,  *[0][No  uindou  records  found  available. ] [OK] *) ; 
return(-l); 

> 

create  uindou  for  RES 
uindous [ neu ] . handle  = 

uiniljcreatB(neukind,  xdesk,  ydesk,  udesk,  hdesk); 

if  (uindous( neu] .handle  < 0)  RES  could  not  make  uindou 

{ 

fornualert(l,  *[0][RES  error  opening  a uindou. | Cannot  continue. ] [OK]* ) 
return( -1); 

> 

y*  fill  uindou  record 

uindous [neu] .type  = neukind; 
uindous [ neu ].fullsize  = FRLSE; 
uindous[ neu) .visible  = FRLSE; 

sot  uindou  title 

uincL-set(  uindous  [neu]  .handle,  UF^RME,  utitie,  0,  0); 

nufluuindous+'t*;  add  uindou  to  count 

return(neu);  return  index 

} 

operLJuindou(ui_ind0x) 

Function:  Make  a uindou  visible. 
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Input:  uii.lndex  = index  to  uindou 

Output:  Nona.  Sets  uorl<  area  and  uisibiiity  flag  in  uindow  record. 

{ 

UDRD  X8ize«  ysize,  uisize,  hsize; 

check  IF  already  open 

if  (uindous[ui.index]. visible) 
return; 

get  current  window  size 

u ind_gst( windows! wi.index]  .handle,  wr^RCVXVUH, 

&X8ize,  &ysize,  &wsize,  &hsiZ8); 

if  no  size,  then  must  bo  first  time  opened 
if  ( I(x8ize  II  yslze  ||  wsize  ||  hsize)  ) 

{ 

xsize  B xdssk;  default  to  desktop  work  area 

ysize  = ydesk; 
wsize  s wdesk; 
hsize  = hdesk; 

> 

open  window 
hide^ouseO ; 

graf.jgroubox(  (xsize  + wsize/2),  (ysize  + hsize/2), 
gr^box,  gr^hbox,  xsize,  ysize,  wsize,  hsize); 
wincLjQpen(windows[wi— index] .handle,  xsize,  ysize,  wsize,  hsize); 
uindows[wi_index] .visible  = TRdE;flag  window  is  open 
shou.jnou8e( ) ; 

> 

ciose.j*iindow(wi.index) 

Function:  Close  a window. 

Input:  wi^index  » index  to  uindow  to  close 

Output:  None.  Closes  window  and  set  visibility  flag. 

{ 

UORD  xsize,  ysize,  usize,  hsize; 

check  if  already  closed 

if  ( !uindows(wi_index] .visible) 
return; 

get  current  uindow  area 

windLget( windows! ui^index] .handle,  I4FJCURRXVUM, 

&xsize,  &ysize,  &usize,  &hsize); 

close  window 
hide^ouse( ) ; 

uindLxiose(uindous!wi.index] .handle) ; 
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graf_shrinkbox( (xsize  + wsize^2)*  (ysiza  + hsize^2), 
gr^box,  gr^box,  xsize,  ysize,  uslze,  hslze); 
ulndous[ul^ndex] .visible  = FRLSE;  flag  uindou  as  closed 
shobLjT!Ouss( ) ; 

> 

deiuuindou(ui_index) 

UORD  ui^ndex; 

Function:  Delete  uiindou  from  RES 

Input:  ui— index  = index  of  uindou  to  delete 

□utput:  None.  Uindou  deleted  from  RES  and  uindous. 

{ 

if  (ulndou8[ui_index] •Visible)/'*  still  on  screen 
close^indou{ui.index) ; /*  so  close  it  */ 

delete  from  RES 

uindLdeie to ( uindous [ui^index] .handle) ; 

/*  set  record  as  available 

uindous [ui^index] .handle  = -1; 
y*  remove  uindou  from  count 
nuoLJUindous--; 

> 

f i nd-u i ndou ( u i_hand i e ) 

UORD  ul-handie; 

Function:  Find  index  for  uindou  record  with  given  handle. 

Input:  ui^andle  = handle  of  uindou  to  search  for 

Output:  Returns  index  or  -1  if  not  found. 

< 

register  int  i; 

for  (1  = 0;  i < KflX-WINDOM;  1++) 

if  (uindous[i ] .handle  ui^andie) 
return(l) ; 
return( -1) ; 

> 

do_redrau(ui_index,  ui^redrau,  x,  y,  u,  h) 

UORD  ui— index, 

(*ui_redrau) ( ) , 

X,  y,  u,  h; 

Function:  Redrau  all  clipping  rectangles. 

Input:  ui_indsx  = index  to  uindou  being  updated 

ui_redrau  =:  address  of  function  used  to  drau  uindou 

X,  y = redrau  area  X,V  coord 

u,  h s redrau  area  uldth  and  height 
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Output:  None.  Screen  Is  updated. 

Notes:  ul^edrau  cannot  use  any  parameters  or  return  any  values. 

You  may  create  a dO— redrau  function  for  each  ulndou, 
or  pass  the  parameters  through  global  variables. 

{ 

GRECT  redrau,  redrau  area 

clip;  currant  clip  area 


hide_mouse( ) ; 
uincL-update(TRUE) ; 
redrau. g_x  = x; 
redrau. g_y  = y; 
redrau. g.ju  = u; 
redrau. g_h  = h; 


freeze  uindou  status 
set  redrau  area 


get  first  clip  rectangle 

ulndUget(ulndous[ul^ndex] .handle,  UF-FIRSTXYUH, 
&clip.g..x,  &clip.g_y,  &clip.g_u,  &cllp.g.Ji); 


begin  redrau  loop  until  no  more  clip  rectangles 
while  (clip.g.ju  &&  cllp.g_h) 

{ 

if  (rc— intersec t(&redrau,  &clip)) 

( 

set^Iip(clip.g_x,  clip.g^j,  clip.guu,  clip.g-h); 
(*ui_redrau]  ( ) ; particuiar  redrau  function  *>' 

} 

uind-get(uindous[ui_index] .handle,  UFJ^EXTXYUH, 

&cllp.g_x,  &cllp.g_jy,  &clip.g_jj,  &clip.gji]; 

} 

ulnd-jupdate(rRL5E) ; screen  Is  ready 

shou_mouse( ) ; 

> 


Bpplication  Functions 
get^f  ile( ) 

Function:  Get  a filename  using  file  selector. 

Input*:  None.  Uses  def_search[]  and  sel.file[]. 

Output:  Exit  button  used  In  feel  dialog  box. 

Sets  default  file  search,  file  selected, 
and  flle.^ame{]  to  contain  the  full  filename. 

{ 

UORO  exit.j3utton; 
char  ^temp; 
int  1; 
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fsel-lnput(dBf-SBarch,  sol»filB,  &BXitJ3utton) ; 


if  ( !exit-J3utton) 

cancelled 

return(exit^utton) ; 

strcpy(file.jnamB,  dsf^earch); 

set  path  *y 

i = strlen( file-name) ; 

temp  = file-name  + (i  - 1); 

point  to  last  character  *y 

while  ( (*tsmp  !=  ’nn') 

y* 

search  for  path  end  */ 

&&  (*temp  !=  ' : ' ) 

y* 

drive  id  *y 

&&  (temp  >s  file-name)  ] 

1 

or  start  of  string  *y 

temp-- ; 

temp++ ; 

y* 

move  to  next  position  *y 

strcpy( temp,  sel— f lie) ; 

y* 

add  file  name 

TB turn (BxltJbut tan) ; 

) 

gBt.llnB(s,  fp,  maxchar) 
char  s[ ] ; 

FILE  *fp; 

UORD  maxchar; 

Function:  6Bt  a linB  of  toxt  from  a filo. 

Input:  s = string  to  storo  lino 

fp  = strBam  fiiB  to  rscBivB  data  from 
maxchar  = max  U of  charactore  to  road 
Output:  Roturns  number  of  characters  read. 

Notes:  Fiie  fp  must  be  open.  Lina  does  NQT  contain  neuline. 

From  K8.R  p-B7- 

{ 

int  c,  i; 
i = 0; 

while  (--maxchar  > 0 &&  (c=gotc(fp))  !=  EOF  &&  c !=  'Nn') 
s(i++)  = c; 
if  (c  ==  ’Nn*) 
s[i++]  = c; 

S[i)  = *N0' ; 

roturn( i ) ; 

) 

load_file() 

Function:  Load  a file  into  the  buffer. 

Input:  None.  Uses  fiie.jname[]  and  buf.line[] 

Output:  Returns  TRUE  if  error  occurred,  else  FRL5E. 

Sets  buf_linen. 

{ 

FILE  »fp; 

char  lin0(«ftX_£CLUHNS],  »tBrap; 

Int  numchar; 
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open  file  *y 

fp  = fapBn(flle^amB«  ’r“); 

If  (fp  ==  NULL)  y*  BPror  opBnlng  file  *y 

{ 

fornujalert(0, * [0] [Cannot  open  file  requested. ][ OK] ') ; 
return ( TRUE ) ; 


y*  read  a line  at  a time  (from  K&R  p.l07) 
max_llne  =0; 
max^olumn  = 0; 

while  ((numchar  = get-1 lne( line,  fp,  KftXJCOLUMNS) ) > 0) 

< 

If  (<nax_line  >=  MfiX_LINES) 

{ 

form-jalert(0,* [0] [Maximum  number  of  lines  read.|No  more  data  will  be  read.] [OK]") 
return(FflLSE) ; 

> 

else  If  ( (temp  s mal loc( numchar ) ) NULL) 

< 

formLjalert(0, * [0] [Out  of  memory. | No  more  data  will  be  read. ] [OK] " ) ; 
re turn (FALSE) ; 

> 

else 

< 

strcpy(temp,  line); 
buf_llne[max— ilne++]  = temp; 

> 

If  (numchar  > max-column)  y*  check  for  max  uldth 
max^olumn  s numchar; 

> 

return (FALSE) ; 

} 

set^llders(ul_lndex) 

Function:  Set  slider  size  and  position. 

Input:  None.  Uses  global  file  sizes. 

Output:  None.  Sets  neu  slider  size  and  position. 

( 

NQRD  xuork,  yuork,  uuork,  huork;  y*  ulndou  work  area  *y 

UORO  hslze,  vslze,  hpos,  v/pos;  y*  slider  size  and  position  *y 

ulndjget ( windows [ul— Index]  .handle,  NF^ORKXYklH, 

&xuork,  &yuork,  &uwork,  &hwork); 
vls_llne  = huork  y ychar; 
vlS-column  = uwork  y xchar; 

y*  find  size  of  slider  *y 

hslze  s ( ( long)vls^alumn  * 1000L)  y ( long)max^oiumn; 
vslze  = ( (long )uls— line  * 1000L)  y ( long)max^llne; 

If  (uslze  > 1000)  vslze  » 1000; 
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if  (hel28  > 1000)  hsize  ° 1000; 
hpos  » ((iang)cur^olumn  * 1000L)  / 

(long) (max^olumn  - vls^oiumn); 

If  (hpos  < 0)  hpos  =:  0; 

v»pos  = ((long)cur^line  * 1000L)  ^ 

( long) (cnaxJ ins  - vis-Jino); 
if  (vpos  < 0)  vpos  = 0; 

uind^et(ulndous[wi^ndex]  .handle,  UF^SLIDE,  hpos); 
uindjset(uindou8[ui^ndex]  .handle,  UF^SLSIZC,  hslzs); 
uilncLj5et(uindou8(ul^nd0x]  .handle,  UF.A/SLIDE,  vpos); 
uindLset(ulndou8(ul^ndex] .handle,  MF_VSL5IZE,  v/size); 
return; 

> 


drau^functlon( ) 


Function:  Orau  in  current  window. 

Input:  None,  cur^indow  Is  Index  to  current  window  to  draw  In. 

Output:  None.  Draws  In  window. 


{ 

NDRD  llne_pOB,  col^os; 

UORD  xwork,  ywork,  wwork,  hwork; 
NORD  box(4]; 
char  *temp; 

NORD  xpos,  ypos; 

NORD  hal,  ual; 


lino  & column  positions 

window  arsa 

clear  screen  array 

max  chars'll Ine 

lino  position  on  screen 

dummy  return  ualuss 


get  window  position  on  screen 

wlnd^et(windows[cur^lndow]  .handle,  UF3iORKXVUH, 
&xwork,  &ywork,  &wwork,  &hwork); 


clear  screen 

usf..lnterlor(8creen-.vhandle,  2); 
usf^tyle(screea^vhandle,  6); 
vsfucolor(8crsea.uhandle,  0); 
box[0]  = xwork; 

box[l]  = ywork; 

box[2]  = xwork  + wwork  - 1; 

box[3]  = ywork  't*  hwork  - 1; 

v_bar(8creen.vhandle,  box); 

ust^llgnment(ecreeri_vhandle,  0,  5,  &hal,  &val); 


outpwt 

xpos  = xwork; 
ypos  = ywork; 

for  (llne^os  = 0;  llne^os  <=  vls^lne;  llns_pos'«’'«’) 

{ 

if  (cur^llne'*‘llne-pos  < max— line)  check  if  iins  in  range 

temp  = buf_llne[cur— llne't'llne-pos] ; 

else 


temp  = blank 
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if  (strlen( temp)  <=  cur-xalumn)  >'*  nothing  uill  be  seen 
temp  +=  strlen(temp); 

else 

temp  +=  cur^oiumn;  adjust  to  proper  start 

v-Justified(8creen^uhandie,  xpos,  ypos, 
temp,  uiuork,  FRLSE,  FRLSE); 
ypos  +=  ychar; 


return; 

> 


control () 

Function:  Master  control  function. 

Input:  None.  Program  initialization  must  be  done  before 

entering  this  function. 

Output:  None.  Returns  for  normal  program  termination. 


< 

OBJECT  *menuLja  dd  r ; 

WORD  end_program  = FALSE; 

WORD  meux , mev/y , 

butstate, 
meubut, 
keystate, 
keycode, 
mbreturn, 
msg.j3uf  [0] ; 

WORD  event, 

menuL-.index; 

WORD  drau^functlonO ; 


address  for  menu 
exit  flag 

evnt^ulti  parameters 


message  buffer 
0vnt_multl  result 
keyboard  menu  title  selected 
/»  screen  drauing  function  */ 


/*  get  address  of  menu 

rsrc_gaddr(0,  NRINMEKU,  &menuuaddr); 


y*  display  menu  bar 

menuJoar  ( menu-jaddr , TRUE ) ; 


initial  button  status  to  uait  for 

butstate  = TRUE;  button  down 


uait  for  a message  indicating  a menu  selection  *y 
do  continue  loop  until  quit 

( 


event  = evnt_multi(  (MU_KEYBD  | MU_MESRB  | MUJ3UTT0N), 


0, 


butstate. 


tt  mouse  clicks 

y*  mouse  buttons  of  interest 
button  state 


0, 


first  rectangle  flags 
x,y  of  1st  rectangle 


0,  0 
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Listing  12-2  (continued) 

0,  0, 

0. 

0,  0, 

0,  0, 
msgjDuf , 

0,  0, 

&m0vx,  &m8vy, 

&mevb(Jt, 

&keystate, 

&keycode, 

&mbreturn] ; 

uilndjupdate(TRUE!) ; 

if  (event  & MU_«ESnG) 

< 

5ujitch(msg_j3uf[0] ) 

i 

case  MNJ5ELECTE0: 

suitch(msgJbuf [4] ) 

I 

case  QUIT: 

endL43rogram  = TRUE; 
break; 

case  INEO: 

do^lalog(INraeQX); 

break; 


height,  uldht  of  1st  rect 
second  rectand  flags 
x,y  of  2nd  rect 

w, h  of  2nd  rect 
message  buffer 

iou,  high  words  for  timer 

x, y  of  mouse  event 
button  state  at  event 
status  of  keyboard  at  event 
keyboard  code  for  key  pressed 
U times  mouse  key  enter  state 

hold  uindou  processing 


menu  chosen 


exit  program 
set  exit  flag 


display  program  info 


case  QPENFILE:  open  a file 

if  ( !get.f ile( ) ) get  a file  name 

break;  cancelled 

if  ( load-f  ile(  ] ) z'*  get  data 

break;  error 

if  (max^line  ==  0 | | max—column  ==  0) 
break;  y*  bad  data 

fileuin  = create^indou( 

( NRME I CLOSER | FULLER | MOVER | SIZER | 

UPRRROU I DNRRROU | V5LI0E | 

LFRRROU I RTRRROU | H5LIDE ) , 
file— name) ; 

if  (fileuin  < 0)  error  creating  uindou 

< 

end-program  = TRUE; 
break; 

> 

openL_uindou(fileuin) ; 

m8nuL.ienabie(menu-^ddr,  OPENFILE,  FRLSE); 
lastcur^line  s cur— line  = 0; 
lastcur-column  = cur_ column  = 0; 
cur-juindou  s fileuin; 
set^iiders(  f i leuin) ; 
break; 
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Listing  12-2  (continued) 

default: 

break; 

> 

reset  menu  title 

menu.tnormal (meniL^ddr,  msg  huf [3] , 1); 

menu_bar(mentL^ddr,  TRUE); 

break;  end  MN«SELECTED 

case  14IU7EDRRU:  redraui  uiindows 

if  ( (cur-juiindcu  = FlndLuindoui(msgj3uf  [3] ) ) < 0) 
break;  no  ulndou  listed 

daL-redrau(cur^lndoij,  draw— function, 

msg-buf  [4] , msg^uf  [S] , insg-J3uf  [6] , msg_buf  [7] ) ; 
break; 

case  UPLNEMTOP:  new  window  Is  on  top 

case  UM-TOPPED: 

If  ( (cur_wlndou  = flnd-ulndow(msg^uf  [3] ) ) < 0) 
break;  no  window  listed 

wlnd-set(windowB[cur-wlndow] .handle,  UF-TOP,  0,  0,  0,  0); 
break; 

case  UMJCLOSED:  close  box  pressed 

If  ( (cur-jwindou  = f lncLjwlndow(msg_buf  [3] ) ) < 0) 
break;  /*  no  window  listed 

deluwlndow(cur-Mlndow) ; 
msnu— lenable (menu_^ddr , OPENFILE , TRUE ) ; 
break; 

case  UM_rULLEO:  full  box  pressed 

if  ( (cur-window  = f lndLulndow(msg_buf [3] ) ) < 0) 
break;  no  window  listed 

if  (windous[cur-window] .fwlisize) 

{ /«  full  to  regular  size 

UORD  newx,  newy,  neww,  newh; 

get  prev/ious  window  size 

wlndLjget(wlndows[cur.window]  .handle,  14F-PREVXYUH, 
&newx,  &newy,  &neww,  &newh); 
wlndLsBt(windows[cur.jwlndow]  .handle,  UF-CURRXYUH, 
newx,  newy,  neww,  newh); 
set-sliders(cur-ulndow) ; 

> 

else 

{ regular  to  full  size 

WORD  xfull,  yfull,  wfull,  hfull; 

got  full  window  size 

wind-get (wlndows[cur^indow]  .handle,  WF— FULLXYUH, 
&xfull,  &yfull,  &wfull,  &hfull); 
wlnd-set(wlndows[cur-window] .handle^  WFJCURRXYWM, 
xfull,  yfull,  wfull,  hfull); 
SBt.j3lidBrs(cur-windou) ; 

> 

wlndows[cur^lndow].full8lze  TRUE; 
break; 
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Listing  12-2  (continiied) 

case  UM_SRROUED: 

if  ( (cur^indou  = f ind-uindou(msg_buf  [3] ) ) < 0) 
break;  no  window  listed 

switch((nsgj3uf[4] ) 

{ 

case  0:  /*  page  up 

cur_line  -=  vis.line; 
break; 

case  1:  page  down 

cur_line  +=  vis^ine; 
break; 

case  2:  /*  row  up 

cur«Jine--; 
break; 

case  3:  row  down 

cur_l  lne++; 
break; 

case  4;  page  left 

cur^olumn  -=  uls_column; 
break; 

case  5;  page  right 

cur^olumn  vis^olumn; 
break; 

case  6:  column  left 

cur-jcolumn-- ; 
break; 

case  7:  column  right 

cur^olumn++; 
break; 
default: 

break; 

> 

/*  check  If  ualues  are  In  range 
if  (cur_llne  >=  max—llne-uis— line  ) 

cur_line  = max— line  - vis-line; 
if  (cur^olumn  >=  max^oiumn-uis-column) 

cur^olumn  s max^olumn  - vis^olumn; 
if  (cur_ line  < 0)  cur. line  = 0; 
if  (cur— column  < 0)  cur^olumn  = 0; 

if  ( lastcur_line  !=  cur— line  ||  lastcur— column  !s  cur^olumn) 

{ 

set— sllders(cur_wlndou) ; 
lastcur— line  = cur— line; 
lastcur^olumn  = cur^olumn; 
msg^uf[0]  = Uh-J^EORRU; 
m8g_buf[l]  = ap— Id; 
msg-buf[2]  = 0; 

msg-buf[3]  = uindows[cur— window] .handle; 
ulndLget(windows[cur^indou]  .handle,  Ur-14DRKXYUH, 

&msg-buf[4],  &msg-buf[5],  &msgJ3uf[8],  lmsg-buf[7]] 
appl-write(ap— id,  16,  msg-buf); 

} 

break; 
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Listing  12-2  (contiimed) 

case  I4M_HSLID: 

if  ( (cur^indcui  = f indJdlndou(msg^uf  [3] ) ) < 0) 
break;  no  wlndou  listed 

cur^olumn  = 

( (Iang)(max^alumn  • vris-jcolumn)  * ( long)msgJ9uf  [4] ) ^ 
1000L; 

if  (cur-column  < 0)  cur^olumn  = 0; 
if  (cur^oiumn  >=  max_column) 
cur^olumn  = max^olumn  - 1; 
if  (iastcur^oiumn  !=  cur_coiumn) 

< 

UORO  xtemp,  ytemp,  wtemp,  htemp; 
set— sliders(cur^indou) ; 
lastcur_iine  = cur^ine; 

uincLjget(uindous[cur^indoui]  .handle,  I4F-140RKXVI4H, 
&xtemp,  &ytemp,  &utemp,  &htemp); 
do^edrau( cur^indou,  drau_f unction, 
xtemp,  ytemp,  utemp,  htemp); 

> 

break; 


case  Ui1_VSLI0: 

if  ( (cur^lndou  = findUjindou(msgJ3uf  [3] ) ) < 0) 
break;  no  uindou  listed 

cur«.line  = 

( (long) (max— line  - vis-line)  * (long)msg_buf [4] ) / 
1000L; 

if  (cur— line  < 0)  cur— line  = 0; 
if  (cur— line  >=  max— line) 

cur— line  = max— line  - 1; 
if  (iastcur— line  cur— line) 

UORD  xtemp,  ytemp,  utemp,  htemp; 
set.j5liders(cur^indou) ; 

Iastcur— line  = cur— line; 

uincl-gBt(uindaus[cur_uindou]  .handle,  UF-i40R{<XyH, 

&xtemp,  &ytemp,  &utemp,  &htemp); 
do— redrau( cur-uindou , drau— f unc t ion , 
xtemp,  ytemp,  utemp,  htemp); 

> 

break; 


case  h[f1L5IZED:  windou  resized  or  moved 

case  WM-MOVEO: 

if  ( (cur-uindou  = fincLj4indou(msgJ3uf  [3] ) ) < 0) 
break;  no  uindou  listed 

if  (msgJ3uf(6]  < WMIK-WIOTH)  msgJ3uf(6]  = WMIlOilDTH; 
if  (msgj3uf(7]  < WMIN-HEIGHT)  msg_buf(7J  = WMIKLHEIGHT; 
uind_set(uindous[cur_uindou] .handle,  UFJCURRXVUH, 

msg-buf[4],  msg-huf [5] , msg-buf[6],  msg-buf [7] ) ; 
se  t-s  1 1 de  r 8 ( cu  r-ju  1 ndou ) ; 
break ; 
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Usting  12*2  (continued) 

default: 

break; 

} end  message  suitch 

) end  message  handler 


If  (event  & MU-KEVBD) 

{ 

su 1 tch ( keycode ) 

{ 

case  QUIT-KEY: 

menu-index  = FILE; 

menu— tnormal(menu^ddr,  menu-index,  0); 

end^rogram  = TRUE; 

break; 

*/ 

default: 

break; 

> 

menu— t norma l(menu_addr,  menu— index,  1); 
menuJbar(menLLjaddr,  TRUE); 

) end  keyboard  handler 

if  (event  & MLLBUTTQN)  button  handler  */ 

( 

butstate  = !(butstate); 

) end  button  handier 


if  (endLprogram) 

{ 

int  i; 


close  open  wlndous 
and  delete  all  uindous 


> 


for  (i  = 0;  i < MftXJJINDOW;  i++) 
if  (ulndous[i] .handle  >»  0) 
del-itiindou(i) ; 


uind-update(FRLSC) ; 

} uhiie  (! endLprogram ) ; 

return; 

> 


resume  processing  *y 
program  control  loop 

end  function 


Main  Program 


main( ) 

< 

int  i,  J; 
WORD  attr[10]; 
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Ustlng  12-2  (contlmied) 

Initialize  GEFI  Rocess 

apLUd  s appl^nit();  Initialize  RES  routines 

if  (ap^id  < 0)  no  calls  can  be  mads  to  RES 

{ ✓»  use  GEMOOS 

Cconuis("***>  Initialization  Error*  <*»»Nn'); 
CconwsCPress  any  key  to  continue. Nn' ) ; 

Crauicin( ) ; 

BXit(-l);  set  exit  v/alue  to  show  error 

> 

screen-phandle  = Got  handle  for  screen 

graf.J-iandlB(&gr_uchar,  &gr_hchar,  &gr_ubox,  &grJnbox); 
8creeru.vhandlB  ° operL.vwork(screen_phandl8) ; 
set^jBcresojattrO ; Get  screen  attributes  */ 

Rpplication  Specific  Routines 

if  ( ! load— resaurce[ "UIND0U2.RSC” ] ] no  resource  file  loaded 

exlt(l); 
lnlt-windous( ) ; 
graf-mouse(RRROU,  0x0L); 

uq  t*ja  t tr  1 bu tes  ( screen. vhandle , a 1 1 r ) ; 
xchar  = attr[0] ; 
ychar  = attr[3]; 

control ( ) ; 

Program  Clean-up  and  Exit 
rsrc— free[ ) ; 

v^l8vuk(8creen— vhandls);  clo8e  workstation 

appl^xitC);  >'»  end  program 

> 


First  comes  the  header  file  WINDOW2.H  for  the  resources  followed 
by  the  variable  filewln.  This  variable  contains  the  window  Index  for 
the  file  being  used.  The  next  set  of  variables  Is  used  to  determine  the 
size  of  the  file  and  the  size  of  the  display.  The  maz-column  and 
maz-Une  variables  have  the  maximum  number  of  columns  and  max- 
imum number  of  lines  contained  in  the  file.  Variables  vis-colunm 
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and  vis-line  count  the  number  of  visible  columns  and  visible  lines 
In  the  window.  Because  the  window  can  change  size.  It  Is  Important 
to  know  how  much  data  Is  visible.  Varislbles  cur-oolnnui  and  cur-line 
keep  track  of  the  starting  column  number  and  line  number  current^ 
shown  in  the  window.  As  the  user  moves  through  the  data  in  the  file, 
knowing  the  starting  position  of  the  data  being  displayed  Is  neces- 
sary. Variables  lastcur-line  and  lastcnr-colnmn  hold  the  previous 
values  of  cnrucolunin  and  cur-line.  The  »diar  and  ychar  variables 
are  used  to  store  the  width  and  height  respectivefy^,  of  the  character 
cell  In  pixela  Constants  MAX-COLUMNS  and  MAX-LINE^  define  the 
maximum  allowable  number  of  characters  per  line  and  of  lines  In  the 
file.  Array  bufLline  Is  an  array  of  pointers  to  strings.  As  the  lines  are 
read  in,  the  bufJine  array  keeps  track  of  them.  The  string  blank  Is 
slmp]^  a blank  line  Flnalty,  there  are  the  default  search  path,  selected 
file,  and  file  name  variables  as  used  in  program  LISTER 

Using  WINDOWl  as  an  outline,  the  GEM-related  functions  remain 
the  same.  Moving  to  the  application  functions  of  WINDOW2,  the  first 
function  encoimtered  is  function  get-fllc( ).  This  function  is  exacts 
the  same  as  in  program  LISTER  The  nect  function,  get-llne( ),  is  a 
more  generalized  version  of  the  getlinef ) function  by  Keml^ian  & 
Ritchie  (Kemlghan,  Brian  & Ritchie.  Dennis,  The  C Programming 
Language,  Prentice-Hall,  1978,  p.  67).  The  get-UneO  function 
presented  here  reads  a line  from  a file.  A line  consists  of  a series  of 
b3Ttes  terminated  by  a newline  character  C\n’).  The  bytes,  read  from 
file  4?  in  the  parameter  list,  are  placed  into  string  parameter  s.  If  the 
number  of  bytes  reaches  the  value  of  parameter  maxchar,  reading 
stops  and  the  function  returns.  So,  either  a neudlne  or  the  maximum 
number  of  characters  will  terminate  a line.  This  function  returns  the 
number  of  characters  read  for  this  line. 

Function  load-file()  opens  the  file  named  in  file-name  and  reads 
the  contents  of  the  file  into  memory  using  get-Unef ).  If  an  error 
occurs  during  opening  or  reading  the  file,  an  alert  box  is  given  and 
the  function  returns  a FALSE  value.  While  reading  the  file,  load-file( ) 
sets  the  maximum  line  length  in  maz-column  and  the  total  number 
of  lines  read  in  max- line. 

Function  set-slidersf ) sets  the  slider  size  and  position  in  the  scroll 
bar.  The  size  and  position  of  the  slider  are  measured  like  the 
graf-slidebox( ) function.  The  size  of  the  slider  can  range  from  0 for 
a slider  of  no  size,  to  1000  for  a slider  covering  the  entire  scroll  bar. 
The  first  bit  of  information  set-sUderQ  needs  is  the  size  of  the 
window  display  in  characters.  Function  wind_get( ) retrieves  the  size 
of  the  work  area  in  ptxela  Hie  size  of  the  file  is  measured  in 
characters  so  that  the  size  of  the  work  area  must  be  converted  from 
pixels  to  characters.  The  number  of  lines  visible  in  the  work  area 
(vis-line)  is  equal  to  the  height  of  the  work  area  in  pixels  (bwork) 
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divided  the  number  of  pixels  per  character  height  (ychar).  Simi- 
lariy,  the  width  of  the  work  area  in  characters  (visucoltimn)  is  found 
by  dividing  the  width  of  the  work  area  (wwork)  by  the  number  of 
pixels  per  character  width  (zdiar).  The  ratio  of  the  slider  size  to  the 
size  of  the  scroll  bar  (1000)  is  equal  to  the  ratio  of  the  size  of  the 
window  display  to  the  size  of  the  total  data  to  display.  Therefore,  the 
ratio  for  the  horizontal  slider  can  be  written  as  this. 

baize  _ visucolumn 

1000  tw«»  ffftlnimi 

To  solve  for  the  relative  slider  size  (hsize),  the  following  equation  is 
used  in  set-slider( ). 

hsize  = (vis-coltmm  * 1000)  / maz-columii 
For  the  vertical  slider,  the  equation  is  this, 
vsize  = (vis-Une  * 1000)  / max-line 

Long  integers  are  used  to  allow  the  multiplication,  which  may  exceed 
the  range  of  standard  integers,  to  occur  first  Since  all  values  are 
integers,  serious  truncation  errors  may  occur  if  the  division  occurred 
first  and  the  results  would  not  be  accurate.  Once  the  slider  sizes  have 
been  calculated,  a test  ensures  that  th^r  do  not  exceed  the  size  of  the 
scrollbar. 

In  program  MOUSE,  you  saw  that  the  position  of  a slider  in  a slide 
bar  using  gra£_alideboz( ) is  measured  at  the  center  of  the  slider  itself. 
The  position  of  the  slider  in  the  window  scroll  box  is  with  respect  to 
the  position  of  one  end  of  the  slider  or  the  other.  For  WINDOW2,  the 
position  of  the  slider  is  with  respect  to  the  bottom  of  the  slider  (see 
Figure  12-7).  For  example,  when  the  slider  is  all  the  way  at  the  top, 
it  is  considered  to  be  at  position  0;  at  the  bottom  it  is  considered  to 
be  at  position  1000. 

In  function  set-sUdersC ),  variables  hpos  and  vpos  are  used  for  the 
horizontal  and  vertical  positions  of  the  sliders.  The  position  of  the 
slider  in  the  scroU  box  is  relative  to  the  position  of  the  displa}^  data 
in  the  file.  The  ratio  for  the  horizontal  scroll  bar  is  this: 

hpos  vis_jcolumn 

1000  max-cohunn  — visucolumn 

If  you  recall  from  program  MOUSE,  the  actual  range  in  which  the 
slider  can  be  moved  is  the  size  of  the  slide  bar  minus  the  size  of  the 
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slider.  As  shown  in  the  ratio  to  calculate  the  size  of  the  slider,  the 
size  of  the  slider  is  equivalent  to  the  number  of  visible  columns  and 
the  size  of  the  scroll  bar  is  equivalent  to  the  total  number  of  columns. 
Therefore,  the  entire  range  of  the  scroll  bar  (1000)  is  equivalent  to 
the  total  number  of  columns  (the  size  of  the  scroll  bar)  minus  the 
number  of  visible  columns  (the  size  of  the  slider).  In  effect  the  size 
of  the  scroll  bar  has  been  reduced  by  the  size  of  the  slider.  To  calculate 
the  relative  horizontal  position.  set_slider( ) uses  this: 

_ (cnr-jcolnmn  * 1000) 

(nunLjcolaiiiii  — vl8.jcoliuiiii) 

The  vertical  position  is  calculated  using  this: 

(corJine  * 1000) 
vpos  = 

(max  line  — viaJine) 

In  function  set-slider( ).  the  long  Integer  values  are  used  for  the  same 
reason  mentioned  above. 

After  the  slider  sizes  and  positions  are  calculated,  they  need  to  be 
set  in  the  window.  Function  wind_set( ) sets  each  value. 

The  dzaw_fnnction( ) routine  draws  the  visible  range  of  data  in  the 
current  window.  The  routine  first  gets  the  position  and  size  of  the 
work  area  on  the  screen.  The  window  is  cleared  with  a call  to  the 
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▼-bar()  VDI  function.  Variable  line-pos  is  used  to  count  the  line 
number  in  the  window.  The  top  line  is  line  0,  and  the  bottom  line 
has  the  value  vis-Jine  The  top  line  corresponds  to  the  string  in  the 
bafUine  array  with  index  cur-line.  Thus,  each  line  in  the  buffer  is 
indexed  by  line-pos  plus  cur-line. 

To  draw  text  on  the  screen,  a VDI  text  output  routine  must  be  used 
for  two  reasons.  First,  the  AES  coordinates  measure  the  upper  left 
comer  of  rectan^es.  This  corresponds  to  the  top  of  a character  ceU. 
Therefore,  the  vst.  .alignmentf ) function  is  used  to  set  top  vertical  text 
alignment  The  second  reason  for  using  a VDI  text  output  function  is 
that  other  tect  output  routines  do  not  recognize  the  clipping  rectangle. 
Because  the  clipping  rectan^e  is  an  important  aspect  of  the  window 
redraw  process,  all  window  output  routines  must  recognize  the  dip- 
ping rectangle.  The  VDI  text  output  routines,  ▼-gtezt( ) and  ▼-justi- 
fiedO,  both  require  a starting  x and  y coordinate  The  variable  xpos 
and  ypos  keep  track  of  the  current  line  position  in  screen  coordinates. 

A for  loop  is  used  to  output  the  lines  on  the  screen.  Since  the 
number  of  lines  to  be  output  is  vis-llne  -H  1,  the  loop  control  variable, 
Une-po8,  starts  at  index  0 and  goes  to  vis-line.  For  each  line  on  the 
screen,  the  line  index  is  tested  to  see  if  it  is  less  than  the  maximum 
number  of  lines.  If  the  index  is  valid,  the  pointer  teiiq>  is  set  to  point 
to  this  line  in  the  buffer.  If  the  index  is  greater  than  or  equal  to 
max-line,  the  index  has  exceeded  the  maximum  number  of  lines  in 
the  buffer  (that  is,  the  window  extends  past  the  end  of  the  data).  In 
this  case,  tenq;>  is  set  to  point  to  the  blank  line  defined  at  the  top  of 
the  program. 

The  next  step  in  displaying  the  line  determines  the  starting  column 
within  the  string.  If  the  length  of  the  line  is  less  than  the  starting 
column,  the  left  edge  of  the  window  starts  beyond  the  end  of  this  line 
so  nothing  should  be  visible.  Pointer  temp  is  moved  to  the  null 
character  at  the  end  of  the  string  so  that  when  the  string  Is  output 
nothing  is  displayed.  If  the  length  of  the  line  is  greater  than  the 
current  starting  column,  pointer  tenqi  is  moved  to  start  at  the  proper 
position  in  the  string.  The  text  is  printed  using  v-jnstified( ).  Unjus- 
tified text  mode  is  used  here.  If  you  want  to  output  justified  text  you 
can  make  the  appropriate  changes.  Once  the  line  has  been  displayed, 
the  y position,  ypos,  is  Incremented  by  the  height  of  a character  cell 

As  a note,  this  particular  draw  function  relies  on  the  activation  of 
the  clipping  rectangle  before  the  text  is  drawn  because  v_jastified( ) 
does  not  stop  output  based  upon  the  parameter  for  the  length  of  the 
string  (wwork).  Function  v_justified( ) uses  this  value  as  a minimum 
length  of  the  string.  If  the  string  exceeds  this  length,  v-justified( ) 
continues  to  print  until  the  end  of  the  string  is  reached.  By  setting 
the  clipping  rectangle,  v-jnstifiedf ) is  prevented  from  printing  beyond 
the  right  edge  of  &e  screen.  Another  reason  the  clipping  rectangle 
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must  be  set  beforehand  Is  that  the  number  of  lines  printed  is  one 
more  than  viaJl&e.  Therefore,  the  last  line  in  the  window  exceeds  the 
window  height  and  needs  to  be  clipped.  In  general,  the  user  would  not 
set  the  window  height  to  hold  an  exact  number  of  lines.  The  program 
can  either  not  print  the  partial  last  line  and  leave  extra  space  or  dip 
the  last  line  as  done  here.  Another  alternative  would  be  to  test  the  size 
of  the  work  area  whenever  the  window  is  resized  and  adjust  the  new 
size  to  an  exact  number  of  lines.  This  same  explanation  also  applies  to 
the  width  of  the  work  area. 

Function  control! ) follows  the  same  structure  as  the  control!) 
function  from  WINDOWl.  In  the  menu  sdections.  the  OPENFILE  case 
opens  a disk  file  and  displays  it  in  the  window.  First,  get-file!)  is 
called  to  allow  the  user  to  select  a file  A FALSE  returned  vdue 
Indicates  that  the  user  has  cancelled  the  open  request  and  the  case 
is  exited.  Otherwise,  the  requested  file  is  opened  and  loaded  through 
load-file!  )•  If  the  loading  is  successful,  maz-Une  and  maz-column 
should  have  values  other  than  0.  If  they  don’t,  either  the  data  was  not 
read  in  properly  or  the  data  cannot  be  read  in  as  text  In  either  case, 
the  function  is  cancelled. 

With  the  data  in  memory,  a window  must  be  opened  and  the  data 
displayed.  The  create-window! ) function  is  used  to  create  the  win- 
dow with  all  control  areas  except  the  Information  line.  These  areas 
are  the  name  box  dose  box  full  box  move  box  size  box  the  up  and 
down  arrow,  the  vertical  slider,  the  left  and  right  arrow,  and  the 
horizontal  slider.  The  title  of  the  window  is  the  filename.  Variable 
file-win  is  set  to  the  index  of  the  window  used  for  the  file.  If  the 
window  was  created  property,  file-win  has  a value  of  0 or  greater.  The 
window  is  then  opened,  and  the  menu  sdection  to  open  a file  is 
disabled.  The  variables  lastenr-line,  cur-line,  lastcnr-column.  and 
car-column  are  set  to  0 so  that  the  display  in  the  window  starts  at 
the  first  line  and  the  first  coltunn.  Variable  car-window  is  set  to 
file-win  and  the  sliders  are  set 

Because  a window  is  created  each  time  a file  is  open,  when  a window 
is  dosed,  it  must  be  deleted  firom  the  system;  otherwise  the  program 
runs  out  of  windows  to  use.  Therefore,  the  WM-CLOSED  case  ddetes 
the  window  instead  of  just  dosing  it 

Not  every  window  interaction  with  the  user  generates  a redraw 
message.  Only  in  cases  where  displayable  area  of  the  window  in- 
creases is  a redraw  message  issued.  For  example,  when  the  window 
becomes  the  new  top  window,  the  work  area  increases  in  size  or 
another  window  is  moved  to  show  more  of  this  program's  window. 
Closing  a window  natiualty  does  not  issue  a redraw  message  because 
the  window  is  no  longer  visible  Moving  a window  does  not  generate 
a redraw  message  because  the  AE^  is  responsible  for  copying  the 
entire  window  contents  from  its  first  location  to  its  final  location. 
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The  arrows,  scroll  boxes,  and  sliders  do  not  automatical^  cause  a 
redraw  message  to  be  issued.  The  AES  does  not  know  what  data  is 
being  represented  in  the  window.  It  does  not  know  what  reaction 
would  be  appropriate.  For  example,  it  does  not  know  the  number  of 
lines  the  window  should  move  or  whether  the  display  is  at  the  end  of 
the  data.  Therefore,  in  the  case  of  arrow  selection,  scroll  bar  selection, 
or  slider  movement  the  redraw  process  must  be  handled  by  the  ap- 
plication. The  redraw  process  can  be  handled  either  by  performing  the 
redraw  function  or  Issuing  a redraw  message. 

The  WM_ARROWED  message  is  used  whenever  the  user  interacts 
with  the  scroll  bar  or  the  arrows.  Element  4 of  the  message  buffer 
contains  a value  indicating  the  control  area  requested  (see  Table 
12-1).  The  page  up.  page  down,  row  up.  or  row  down  requests  cor- 
respond to  a click  above  the  slider,  a click  below  the  slider,  or  clicking 
the  up  or  down  arrows,  respective^.  Page  left,  page  right,  column  left 
and  column  right  correspond  to  the  horizontal  scroll  bar  and  arrows. 


Table  12-1:  Message 
WM-ARROWED 
Border  Selections 


Value 

Selection 

0 

Page  up 

1 

Page  down 

2 

Row  up 

3 

Row  down 

4 

Page  left 

5 

Page  right 

6 

Column  left 

7 

Column  right 

Depending  upon  the  request  the  sqipropriate  action  upon  cnr-Une 
or  cur_colunm  is  taken  in  each  event  If  the  event  is  a page  up  or 
down,  the  current  line  is  decreased  or  Increased  by  the  number  of 
visible  lines  (for  example,  one  page).  An  up  or  down  curow  causes  the 
current  line  to  be  decreased  or  increased  by  one  line.  Similar  actions 
are  taken  for  the  horizontal  movements. 

After  the  current  line  or  column  Is  changed,  the  new  value  must  be 
tested  to  see  if  it  remains  within  the  range  of  the  data.  WINDOW2 
does  not  allow  the  user  to  move  the  window  past  the  end  of  the  file 
The  tests  keep  the  starting  line  and  column  greater  than  or  equal  to 
0 and  within  one  screen  size  of  the  end  of  the  data.  Now  that  the  new 
starting  line  or  column  is  known,  the  window  must  be  redrawn  to 
show  the  new  area  of  data.  If  the  new  starting  line  or  column  is  the 
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same  as  the  old  starting  line  or  column,  the  user’s  request  causes  no 
changes  to  the  display  and  the  redrawing  is  skipped. 

The  WM-ARROWED  case  sends  a message  to  initiate  the  redraw 
process.  First  the  new  slider  positions  are  set  Then  the  current  value 
becomes  the  previous  value.  To  send  a message,  the  message  buffer 
must  be  filled  with  the  proper  values.  Element  0 is  the  message  type, 
so  it  is  filled  with  the  WM-REDRAW  constant  value.  Element  1 is  the 
ID  nvimber  of  the  application  sending  the  message.  Since  this  mes- 
sage fits  within  the  16  b3des  allowed,  element  2 is  O.  'For  a redraw 
message,  element  3 must  contain  the  handle  of  the  window  to  redraw 
and  elements  4,  5,  6,  and  7 define  the  redraw  area.  Since  this  is  the 
top  window,  the  entire  work  area  is  visible  and  needs  to  be  redrawn. 
The  function  rqipL-writeO  sends  the  message  to  the  AE^,  which,  in 
turn,  routes  the  message  to  the  £q)proprlate  application.  In  this  case, 
WINDOW2  is  writing  a message  to  itself.  This  technique  is  shown  here 
to  demonstrate  the  process  of  sending  a message  to  an  application. 
Generally,  an  application  would  not  send  a message  to  itself. 

Cases  WM-HSLID  and  WM-VSLID  respond  to  the  new  slider  posi- 
tions requested  by  the  user.  In  these  messages,  element  4 of  the 
message  buffer  contains  the  new  position  of  the  slider.  From  this  new 
position,  a new  current  line  is  calculated  based  upon  the  equations 
discussed  above.  In  the  equation  used  in  these  cases,  iii8g.biifI4] 
represents  hpos  or  vpos  in  WM-HSLID  or  WM-VSLID,  respectivety.  If 
a new  current  line  or  column  has  been  requested,  the  do_redraw( ) 
function  is  called  to  redraw  the  window.  Calling  the  do_rediaw() 
function  directly  is  much  more  efficient  than  having  the  program 
send  a message  to  itself. 

Finally,  in  function  main()  all  Initialization  procedures  are  the 
same  as  in  WINDOWl.  The  ^obal  variables  ludiar  and  ychar  are  set 
with  the  values  returned  by  the  vqt-attributes( ) function.  Then  func- 
tion controlf ) is  called. 

That  about  does  it  for  this  program.  As  for  testing  the  program, 
read  in  some  of  the  source  code  files  you  have  created  for  this  book. 
If  you  entered  program  WINDOW2  as  shown  in  Listing  12-2,  your 
source  file  should  have  over  1000  lines.  If  you  try  to  read  this  source 
file  vrith  the  WINDOW2  program,  the  alert  box  indicates  that  the 
maximum  number  of  lines  has  been  reached.  To  enhance  the 
program,  add  another  window  so  the  user  can  open  more  than  one 
file  at  a time.  To  do  this,  you  need  to  keep  track  of  which  window 
belongs  to  which  file.  You  might  want  to  create  your  own  data  struc- 
ture to  keep  track  of  this  relationship. 

You  have  seen  and  used  most  of  the  GEM  and  Atari  functions 
accessible  through  the  C programming  language.  A complete  opera- 
tional listing  of  all  functions  is  given  In  ^pendix  A.  The  appendices 
also  include  constant  definitions,  standard  header  files,  and  useful 
tables. 
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Enjoy  programming  your  Atari  ST.  Remember  to  keep  your 
programs  organized  and  modular.  To  use  WINDOWl  or  WINDOW2  as 
an  outline  file,  simpfy  delete  the  statements  in  the  sections 
plicatlon-Speciflc  Data.  Application  Functions,  and  Application- 
Specific  Routines  in  function  malnO.  Study  the  programs  presented 
in  this  book  and  don’t  be  aiiaid  to  experiment  with  them,  especially 
the  AES  programs.  Menus,  windows,  and  the  graphic  interface  change 
the  way  a program  looks.  Full  utilization  of  GEM  and  Atari  routines 
can  give  a program  professional  elegance  and  sophistication. 


APPENDIX  A 

C Function 
Reference  Guide 


This  appendix  is  a reference  guide  to  all  functions  defined  in  the  Atari 
^tem  developer's  documentation.  The  function  names  and  parame- 
ter lists  given  here  are  in  accordance  with  Atari  documentation.  The 
exact  syntax  of  a function  name  (for  example,  upper-  or  lower-case 
letters)  may  vary  depending  upon  the  compiler  used.  If  you  get  a syn- 
tax error  or  undefined  reference  with  respect  to  a function  name, 
check  your  compiler  manual  to  see  if  the  function  is  implemented  and 
to  che^  the  syntax. 

The  various  portions  of  the  operating  ^tem  have  some  standard 
features  that  apply  to  the  function  usage.  First  of  all.  the  GEMDOS, 
BIOS,  and  XBIOS  fimctions  are  all  defined  as  macros  in  the  header  file 
OSBIND.H  (see  Appendix  B).  Therefore,  any  program  that  uses  these 
functions  must  include  OSBIND J1  at  the  start  of  the  program. 

The  VDI  function  parameters  follow  a specific  format  All  parameter 
lists  for  VDI  functions  start  with  a handle  parameter.  This  handle 
refers  to  the  workstation  on  which  the  function  has  an  effect  The 
only  functions  that  do  not  follow  this  format  are  v-opnv^)  and 
v_<qpnvwk().  as  they  create  workstations. 

All  VDI  function  names  begin  with  “v_”  characters.  Whenever  a 
point  is  required  by  a VDI  function,  it  is  passed  in  an  array.  The  x 
coordinate  is  alvirays  followed  by  the  y cooidinate.  For  example,  in  an 
array  called  sanqile,  element  8anq;>le[0]  would  be  the  first  x coordinate 
and  8anqple(l]  its  corresponding  y coordinate.  Subsequent  points  are 
placed  sequentially  in  the  £uray.  Whenever  a rectangle  is  required,  it  is 
passed  as  a pair  of  points  in  an  array  (i.e.,  four  elements).  The  first 
point  defines  the  location  of  the  upper  left  comer  of  the  rectan^e,  and 
the  second  point  provides  the  coordinates  for  the  lower  right  comer. 
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The  last  comment  with  respect  for  the  VDI  refers  to  the  Input 
modes.  The  VDI  allows  two  input  modes  for  the  input  devices;  request 
and  sample.  A request  function  waits  until  input  is  available  from  the 
device.  A sample  function  tests  the  device  to  see  if  data  is  available.  If  it 
is  not  the  program  continues  and  the  function  indicates  that  no  data 
was  found.  If  data  is  available,  it  is  acted  upon  and  this  status  condi- 
tion is  returned  by  the  function. 

The  AES  uses  a different  method  of  specifying  a rectangular  area 
than  the  VDI.  The  AES  uses  four  values  providing  the  coordinates  of 
the  upper  left  comer  of  the  rectangle  and  its  width  and  height  Unlike 
VDI  coordinates,  AES  coordinates  always  refer  to  screen  pixels  and  are 
device-dependent  Therefore,  the  width  and  height  of  a rectangle  ex- 
tend to  the  right  and  down  from  the  coordinates  given.  A rectangular 
area  required  by  an  AES  flmction  will  be  supplied  through  four  indi- 
vidual parameters. 

The  functions  are  listed  alphabetically  below.  In  cases  where  the 
fimctlon  name  includes  the  underscore  character  (_),  the  name  is 
alphabetized  as  if  the  underscore  did  not  exist  Following  the  function 
descriptions  is  a list  of  the  function  grouped  by  usage. 

WORD  appL-esit  ( ) 


Remove  an  application  from  the  AES.  When  this  function  is  called,  the 
calling  application  is  removed  from  GEM  AEIS  and  the  AES  cleans  up 
the  environment  variables  and  arrays.  A positive  integer  is  returned  if 
successful;  otherwise  0 is  returned. 

WORD  (ly-ipname) 

char  *iy-fy>name; 

Find  the  application  ID  of  another  application  in  the  qrstem.  Parame- 
ter apJfyname  points  to  a string  of  eight  characters  containing  the 
filename  of  the  application  to  locate.  The  string  must  contain  eight 
characters.  If  the  filename  Is  less  than  eight  characters,  the  pro- 
grammer must  fill  the  remaining  characters  with  blank  spaces.  A — 1 
returned  value  means  that  the  application  could  not  be  located  by  the 
AES. 

WORD  ^pl-iiiit( ) 

Initialize  the  internal  arrays  used  by  the  GEM  AEIS.  An  application  ID 
number  is  returned.  If  the  ID  is  — 1,  the  function  call  was  unsuccessful. 
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WORD  ai^l-iead  (ap_rid,  ^-xlen^,  iq[>-xpbiiff) 

WORD  ap-iid, 

ap-rlength; 
char  *ap_rpbiif^ 

Read  a message  waiting  for  an  application.  When  a message  event 
occurs,  the  event  function  fills  a 16-b3rte  message  buffer.  If  more  than 
16  bj^es  are  in  the  message,  this  function  is  used  to  read  the  remain- 
ing data  Parameter  ap_ild  Is  the  ID  number  of  the  application  that 
sent  the  message,  and  i^-rlengOi  is  the  number  of  bytes  to  read.  The 
ap-Tpbaff  string  is  a buffer  to  hold  the  data  being  read.  A returned 
value  of  0 indicates  an  error. 

WORD  i^L.tpli7  i9_tpnam,  iqi^^pscale) 

char  *ap_tpmem; 

WORD  ap^num, 

(^.Jpscale; 

Play  a portion  of  pre-recorded  GEM  AES  user  actions.  After  a user's 
actions  have  been  recorded,  this  function  can  be  used  to  replay  them. 
Tlie  parameter  ap-tpmem  points  to  the  user  events  to  be  played. 
Parameter  ap-tpnum  indicates  the  number  of  actions  to  be  played. 
Parameter  iqi_^pscale  sets  the  replay  speed  ranging  in  value  from  1 to 
10,000.  A value  of  50  is  half  speed.  100  is  full  speed,  and  200  is  twice 
speed.  The  returned  value  always  equals  1. 

WORD  iq>pl_ttecord  (ap-trmen,  ^.trcount) 
char  *ap-trmem; 

WORD  ap-trcount; 

Record  a specified  number  of  user  actions.  As  the  user  interacts  with 
the  application,  this  function  records  the  user’s  actions.  Parameter 
{^-tmiem  points  to  a segment  of  memoiy  where  the  actions  will  be 
stored,  and  ap_trcount  is  the  number  of  actions  to  record.  The  func- 
tion returns  the  number  of  actions  actually  recorded. 

E^ch  action  is  stored  as  a two-part  data  item.  The  first  part  consists 
of  two  bytes  (16  bits)  to  indicate  the  event  code  as  follows: 


0 timer  event 

1 button  event 

2 mouse  event 

3 keyboard  event 


The  next  four  b}rtes  contain  information  regarding  the  event  in  the 
following  format: 
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timer  event 
button  event 

mouse  event 

kQdx>ard  event 


the  number  of  milliseconds  elapsed 

low  word:  button  state  as  defined  In  the  text 

high  word:  number  of  clicks 

low  word:  mouse  x coordinate 

high  word:  mouse  y coordinate 

low  word:  keyboard  character  code 

high  word:  keyboard  state  (see  text) 


WORD  i^pl-wilte  (i4>-wid,  iq>-wleii^,  iq;>-wpbuff) 

WORD  ^.wid, 

i^-lengUi; 

char  *^-wpbtifiE; 

Write  a message  to  the  AES.  This  function  writes  a message  to  an 
application  in  the  ^tem.  The  message  is  in  the  buffer  ap-wpbufif  The 
nvunber  of  bytes  is  specified  by  ap-wlength  and  the  application  ID  to 
write  to  is  ^-wid.  A returned  value  of  0 indicates  an  error. 

long  Bconin(dev) 

WORD  dev; 

Wait  for  a character  to  be  returned  from  the  device  specified  by  dev. 
The  character  is  returned  in  the  low  WORD  of  the  long  value.  If  bit  3 of 
the  ^tem  variable  conterm  is  set  the  high  WORD  contains  the  value 
of  the  sfystem  variable  kbshift  when  the  was  pressed  (see  .^pendix 
D,  System  Addresses). 

VOID  Bconout  (dev.  c) 

WORD  dev,  c; 


Walt  until  the  character  c has  been  written  to  device  dev. 


WORD  Bconstat  (dev) 

WORD  dev; 

Get  the  input  status  of  a character  device.  The  function  returns  — 1 if 
characters  are  available,  or  0 if  not  The  device  numbers  are: 


Number 

Device 

0 

PRT:  — parallel  printer  port 

1 

AUX:  — auxUiaiy  RS-232  port 

2 

CON:  — console/keyboard 

3 

MIDI  port 

4 

KQi)oard  port  (Atari  extension) 

5 

Raw  console  output 
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For  these  devices,  the  le^  BIOS  operations  are: 


Operation 

PRT: 

AUX: 

CON: 

MIDI 

Kbd 

Raw 

Bconstat( ) 

no 

yes 

yes 

yes 

no 

no 

BconinO 

yes 

yes 

yes 

yes 

no 

no 

Bconout( ) 

yes 

yes 

yes 

yes 

yes 

yes 

Bcostat() 

yes 

yes 

yes 

yes 

yes 

no 

The  MIDI  device  has  an  interrupt-driven  Input  buffer  of  80  characters. 
The  kqdjoard  device  (4)  Is  output  onty  and  can  be  used  to  configure 
the  Intelligent  k^board  (see  Atari  documentation  for  further  details). 
The  raw  console  device  outputs  characters  to  the  screen  without 
interpretation  of  control  or  esc^>e  sequences. 

long  Bcostat  (dev) 

WORD  dev; 

Return  — 1 if  device  dev  Is  ready  for  output,  or  0 if  not  See  function 
Bconstat( ) for  values  of  dev. 

VOIDBioskeysO 

Restore  the  initial  ^tem  settings  for  the  keyboard  translation  tables 
(see  the  B^yfbl( ) function). 

WORDCaudnO 

Read  a character  from  the  auxUlaiy  port  (handle  1).  This  port  is  nor- 
malty  the  serial  port 

WORDCauzlsO 

Check  the  status  of  the  AUX:  input  If  a character  Is  ready  to  be  read, 
OxFFFF  is  returned.  Otherwise  0 is  returned. 

WORD  Canzos  ( ) 

Check'  the  status  of  the  AUX:  output  If  it  is  ready  to  receive  a charac- 
ter, OxFFfF  is  returned.  Otherwise  0 Is  returned. 

VOID  Caozout  (c) 

WORD  ct 
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Write  the  character  c to  AUX:,  the  auxiliary  port  (handle  1).  The  high 
eight  bits  are  reserved  and  must  be  0.  This  port  is  usualfy  the  serial 
port 

longCconinO 

Read  and  echo  a character  from  the  standard  input  If  the  standard 
input  device  is  the  console,  the  long  value  returned  contains  both  the 
ASCII  and  the  console  scan  codes  in  the  following  format 


Bits 

Contents 

0-7 

ASCII  character  code 

8-15 

AUO 

16-23 

Scan  code  or  0 if  not  console 

24 

Right  shift 

25 

Left  shift  key 

26 

Control  key 

27 

Alternate 

28 

Caps  Lock  key 

29 

Ri^t  mouse  button  or  Clr/Home  k^r 

30 

Left  mouse  button  or  Insert  k^r 

31 

Reserved 

For  bits  24-31,  if  the  bit  is  set  to  1,  the  kqr  is  depressed. 

WORD  Cconis  ( ) 

Check  the  status  of  the  standard  input  If  a character  is  available,  the 
function  returns  OxFFFF.  Otherwise  0 is  returned. 

WORD  Cconos  ( ) 

Check  the  status  of  the  standard  output  If  the  standard  output  is 
ready  to  receive  a character,  this  function  returns  OxFFFT'.  Otherwise 
0 is  returned. 

VOID  Cconout  (c) 

WORD  c; 

Write  the  character  with  ASCII  value  in  c to  the  standard  output  The 
high  eight  bits  are  reserved  and  must  be  0. 

VOID  Cconrs  (buf) 

char  *bnf; 
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Read  a string  from  the  standard  input  Common  line  editing  charac- 
ters are  interpreted: 


Character 

Function 

Return  or  Ctri-J 

End  ofline 

Ctrl-H  or  Delete 

Remove  last  character 

Ctrl-UorCtrl-X 

Erase  entire  line 

Ctri-R 

Retype  the  line 

Ctrl-C 

Terminate  the  process 

The  element  bof  [0]  contains  the  number  of  characters  typed.  Ele- 
ment buf  [1]  contains  the  number  of  character  read  on  exit  Element 
buf  [2]  is  the  first  character  of  the  string  entered.  The  string  may  or 
may  not  be  null-terminated. 

VOID  Cconws  (8tr) 
diar  *str; 

Write  the  null-terminated  string  str  to  the  standard  output 

long  Cnedn  ( ) 

Read  a character  from  the  standard  input  If  the  input  device  Is  CON:, 
no  echoing  Is  done  and  control  characters  are  Interpreted. 

WORD  Cpmos  ( ) 

Check  the  status  of  the  PRN:  output  If  It  Is  ready  to  receive  a char- 
acter. OxFFFF  Is  returned.  Otherwise  0 is  returned. 

VOID  Cpmout  (c) 

WORD  c; 

Write  the  character  c to  PRN;  the  printer  port  (handle  2).  The  high 
eight  bits  are  reserved  and  must  be  0. 

long  C^awdn  ( ) 

Read  a character  from  the  standeud  input  (CON:,  handle  0)  without 
echo. 

long  Ctawio  (w) 

WORD  w; 
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Read  or  write  to  the  standard  Input/output  If  w is  QxOOFF.  a character 
is  read.  If  no  character  is  available.  0 is  returned.  If  w is  not  OxOOFT. 
the  character  w is  written  to  the  standard  output 

WORD  Cnraconf  (op.  data) 

WORD  op,  data; 

Configure  the  VT52  emulator  cursor.  The  configuration  function  to 
perform  depends  on  the  value  of  op  as  follows: 


op Function. 

0 Hide  cursor 

1 Show  cursor 

2 Set  blinking  cursor 

3 Set  nonblinking  cursor 

4 Set  blink  rate  according  to  value  In  data 

5 Return  current  cursor  blink  rate 


The  cursor  blink  rate  is  based  on  the  vertical  blank  interrupt  rate.  On 
the  monochrome  monitor,  this  occurs  at  70  Hz.  On  the  color  monitor, 
this  occurs  at  60  Hz  in  NTSC  mode  or  50  Hz  in  PAL  mode.  The  time 
for  the  cursor  to  turn  off  and  back  on  again  is  twice  the  value  of  data 
divided  by  the  vertical  blank  rate. 

WORD  Dcxeate  (pathname) 
nfiflr  *patlin8iiic$ 

Create  a diiectoiy  specified  by  the  string  pointed  to  by  pathname.  The 
string  gives  the  complete  path  for  the  new  directory.  0 is  returned  if 
successful,  otherwise  an  error  value  is  returned. 

WORD  Ddelete  (pathname) 
char 

Delete  the  directory  specified  by  the  path  name  pointed  to  by  path- 
name. The  directory  must  be  empty  and  may  not  be  the  the  or  “. ." 
special  directories.  0 value  is  returned  on  success,  or  an  error  value  is 
returned. 

VOID  Dfree  (bof;  diiveno) 

stract  dtok-info  *bafi 
WORD  drtveno; 
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Get  the  allocation  infonnatlon  about  the  drive  specified  in  diiveno. 
Drive  0 is  the  defoult  drive.  1 is  drive  A.  2 is  drive  B,  etc.  Hie 
disk-info-buf  structure  is  filled  by  the  function  and  is  defined: 


struct  disk-info  { 
long  b-free; 
long  b-totah 
long  b-secsiz; 
long  b-dsiz; 

} 


/*  * of  firee  clusters  on  drive  */ 
/*  total  * of  dusteis  on  drive  */ 
/*  * of  bytes  in  a sector  */ 

I*  * sectors  in  a duster  */ 


With  this  information,  the  application  can  determine  the  amount  of 
available  space  on  the  drive. 


WORDDgetdrvO 

Returns  the  number  of  the  current  drive  with  0 = A.  1 = B.  etc 


VOID  Dgetpath  (bn^  drivmo) 
diar  *bufi 

WORD  driveno; 

Get  the  current  directory  path  for  a drive.  The  path  is  placed  into  bnl 
The  drive  number  is  0 for  the  default  drive,  1 for  drive  A.  2 for  drive  B, 
etc.  The  s^plication  must  suppty  enough  space  in  bof  to  hold  the  path 
name. 


VOID  Dosonnd  (ptr) 
diar  *ptr; 

Initiate  the  sound  daemon's  "program  counter"  to  the  address  con- 
tained in  ptr.  A daemon  is  an  independent  process.  The  series  of  bytes 
pointed  to  by  ptr  contain  instructions  and  data  for  the  sound  daemon. 
The  Instructions  are: 


instructton Function 

QxOO-OxOF  Put  the  next  byte  into  the  sound  register.  QxOO  puts  the  data 
into  roister  0,  QxOl  puts  it  Into  register  1,  etc. 

0x80  Put  the  next  byte  into  the  temporary  raster  (temp_reg) 

0x81  Uses  the  next  three  bytes,  calling  them  reg_no,  bytel,  and 
byte2,  where  reg_no  is  the  register  to  use.  bytel  is  the 
increment  value,  and  byte2  is  the  termination  value.  The 
following  procedure  is  performed: 

Until  value  in  temp_r^  = byte2 
Put  value  from  temp_r^  into  r^_no 
Add  bytel  to  temp_r^ 

Repeat 
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Instruction 

Function 

Qx82-0xFE 

OxFF 

The  next  b3rte  contains  the  number  of  1/50  second  time  units 
to  wait  before  continuing 

If  the  next  byte  is  0.  the  second  daemon  stops.  Otherwise  the 
value  is  used  like  instructions  0x82  to  OxFE 

long  Ihcvnii4>( ) 

Return  a value  with  bit  settings  indicating  which  drives  are  available. 
If  the  bit  is  set  to  1.  the  drive  is  available  at  that  location.  Bit  0 corre- 
sponds to  drive  A.  bit  1 for  drive  B,  eta 

long  Dsetdnr  (drv) 

WORD  dry. 

Set  the  default  drlva  The  value  in  drv  detemlines  the  new  default 

drive  with  0 = A,  1 = B 15  = P.  The  value  returned  has  its  low  16 

bits  set  to  1 for  each  drive  available  (bit  0 = A.  bit  1 = B.  eta).  A drive  is 
available  if  its  directory  has  been  used.  Onty  16  drives  are  available. 

WORD  Dse^ralli  (patfi) 
char  *path; 

Set  the  current  directory  path  to  the  path  name  pointed  to  by  path.  0 
is  returned  if  successful;  otherwise  an  error  value  is  returned. 

WORD  evnt-button  (ev-bclicks,  ev-bmask,  ev-bstate, 
ev-bmz,  ev-bn^,  ev_bbntton,  ev-bkstate) 

WORD  ev-bcUcks. 

ev-bmask, 

ev_bstate, 

*ev-bms,  *ev-bmy, 

*ev_bbutton, 

*ev-bk8tate; 


Wait  until  a mouse  button  is  clicked.  Depending  upon  the  input 
parameters,  this  function  responds  onfy  to  a certain  combination  of 
mouse  buttons  and  a certain  number  of  dicks.  The  returned  value  is 
the  number  of  times  the  specified  state  had  been  achieved.  The 
parmeter  are  used  as  follows: 


ev_bdlcks  the  number  of  dldcs  needed  for  the  event 
ev_bmask  the  mask  for  the  buttons  of  Interest  GEM  AES  can  handle  up 
to  16  buttons  where  bit  0 refers  to  the  furthest  left  button. 
When  the  bit  Is  set  to  1,  that  button  Is  used. 
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ev_bstate 


ev_bmx 

evJamy 

evJDutton 

evJskstate 


the  state  to  detect  for  each  button.  The  bits  are  in  the  same 
order  as  ev_bmask  and  have  the  following  meaning: 

0 = button  up 

1 = button  down 

the  X coordinate  of  the  mouse  pointer  when  the  event 
occurred 

the  y coordinate  of  the  mouse  pointer  when  the  event 
occurred 

the  state  of  the  mouse  buttons  upon  exit  from  the  routine. 

The  bit  settings  are  the  same  as  ev-bstate. 
the  keyboard  state  when  the  function  returned.  The  bits  In 
this  value  have  the  following  meaning: 

Bit  1 right  shift 

Bit  2 left  shift 

Bit  3 Control  key 

Bit  4 Alternate  key 

If  the  bit  Is  set,  the  key  has  been  pressed. 


The  returned  value  of  the  function  is  the  number  of  times  the  but- 
ton(s)  actually  entered  the  desired  state.  This  value  is  never  less  than  1 
or  greater  than  ev-bdicks. 

WORD  evnt-dclick  (ev_dnew,  ev-dgetset) 

WORD  e!v_dnew, 
ev_dgetset; 

Set  or  read  the  double-click  speed  for  the  mouse  button.  When  ev_dget- 
set  is  1,  the  double-click  speed  is  set  to  the  value  in  ev_dnew  and  this 
value  is  returned  by  the  function.  Otherwise,  the  current  double-cllck 
SF>eed  is  returned  by  the  function.  The  speed  can  range  from  0 as 
slowest  to  4 as  fastest 

WORD  evnt-keybd  ( ) 

Walt  for  a kQisoard  event  The  application  processing  stops  until  a 
keyboard  event  for  the  application  is  reported  by  the  AES.  The  re- 
turned value  is  the  keyboard  code  (see  i^pendlx  C)  for  the  character 
^l)ed. 

WORD  evnt-mesag  (ev_mgpbuff) 
char  *ev_mgpbufE; 

Wait  for  a message  event  When  a message  is  sent  to  an  application, 
the  AES  issues  a message  event  to  the  receiving  application.  This 
function  acknovdedges  the  message  event  and  reads  a standard  16- 
byte  message  from  the  AES.  The  16  bytes  are  placed  in  the  buffer 
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pointed  to  by  ev-m^buff.  The  formats  for  the  pre-deflned  AES  mes- 
sages are  given  In  i^pendix  E. 

WORD  evnt-monse  (etr_moilag», 

ev-mox,  ev_moy,  cv_mowidth,  ev_moheight, 
ev-momx,  ev_momy,  ev-mobutton,  mv_mokstate) 
WORD  mnflags, 

ev_moz,  ev_moy, 
ev_mowidth,  ev_moheight, 

*ev_momx,  *ev_momy, 

*ev_mobutton, 

*ev_mokstate; 

Walt  for  the  mouse  to  enter  or  leave  a specified  rectangle.  The  parame- 
ters are  as  follows; 


ev_moflags 


ev_mox 

ev_moy 

ev_mowldth 

ev_]iiohelght 

ev_momx 

ev_momy 

ev_mobutton 


ev-mokstate 


a value  of  0 means  to  wait  for  the  mouse  to  enter  the 
rectangle.  A value  of  1 means  to  wait  for  the  mouse  to 
exit 

the  X coordinate  of  the  upper  left  comer  of  the  rectangle  In 
screen  coordinates. 

the  y coordinate  of  the  upper  left  comer 
the  width  of  the  rectangle  In  pixels 
the  height  of  the  rectangle  in  pixels 
the  X coordinate  of  the  point  where  the  mouse  event 
occurred 

the  y coordinate  of  the  point  where  the  mouse  event 
occurred 

the  state  of  the  mouse  buttons  when  the  event  occurred. 
Bit  0 corresponds  to  the  furthest  left  button.  A 1 value 
means  the  button  was  pressed, 
the  status  of  the  koboard  special  function  kQ«.  If  a bit 
is  1,  the  k^  was  pressed.  Itie  bits  are  used  as  follows: 

Bit  0 ri^t  shift 

Bit  1 left  shift 

Bit  2 Control  k^ 

Bit  3 Alternate  key 


The  fimctlon  always  returns  the  value  1. 

WORD  evnt_multi  (ev-mfings,  ev-mbclicks,  ev_mbmask, 

ev-nibstate,  ev-mmlllags,  ev.  rnmlx,  ev^mmly, 
ev_mml  width,  ev-mmlheight,  ev-mm2flags, 
ev_mm2z,  ev-mio2y,  ev_mm2widt]i,  ev-inm2helght, 
ev_mmgpbuff,  ev_mtlocount,  ev-mthicount,  ev-mmox, 
w-joamayt  ev-mmobiitton.  ev-mmokstate, 
ev-mbretuin,  ev_mbtetum) 
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WORD  ev-nmifiagB, 

ev_mbclick8,  ev-mbmask,  ev-mbstate, 
ev^miiilflagBi  ev-mmlz,  ev^mmly, 
ev-mml  width,  ev_minlhel^t, 
ev-mm2flags,  ev-tnm2a,  ev_mm2y, 
ev_jnin2width,  ev_mm2helght, 
ev-mtlocoont,  ev^mthicoimt, 

*ev-mmox,  ^ev-mmoy, 

*ev-mmobutloii,  ^ev-mmokstate, 

*ev-mkretum,  *ev_inbxetiixii; 
char  *ev-in]iigpbiiff; 

Walt  for  any  one  of  six  possible  events.  This  function  combines  evnt_ 
buttonO,  6fvnt-kQd>d( ),  evnt-mesag( ),  evnt_moiise( ),  and  evnt_ 
timer( ) into  one  function  call.  The  eventfa)  to  wait  for  are  specified  by 
the  bits  in  ev-mflaga.  Any  combination  of  events  is  valid.  The  param- 
eters are  basically  the  same  as  those  used  for  the  various  independent 
event  functions,  and  are  used  as  follows: 


ev_mmflags  a set  of  bits  indicating  the  event(s)  to  accept  If  the  bit  is 
set  to  1,  the  function  responds  to  that  event  The  bits 
are  specified  as  follows  and  have  the  associated  defined 
constants: 


Bit 

Constant 

Value 

Event 

0 

MUJKEYBD 

QxOOOl 

keyboard 

1 

MU-3UTTON 

0x0002 

mouse  button 

2 

MU-Ml 

0x0004 

first  mouse  rectangle 

3 

MU-M2 

0x0008 

second  mouse  rectangle 

4 

MU-MESAG 

0x0010 

message 

5 

MU^TIMER 

0x0020 

timer 

ev_mbclicks  the  number  of  dicks  for  a button  event 

ev_mbmask  the  mouse  buttons  of  interest  Bit  0 corresponds  to  the 
furthest  left  button.  A bit  set  to  1 means  that  button 
was  used. 

ev_mbstate  the  state  of  the  mouse  buttons.  A bit  set  to  1 means  the 

button  is  down. 

ev_mm  Iflags  first  rectangle  event  flag.  A value  of  0 causes  an  event 

when  the  mouse  enters  the  rectangle 
ev_mmlx,  ev_mmly,  ev_mmlwldth,  and  ev_mmlheight 

these  parameters  define  the  location  and  size  of  the  first 
mouse  event  rectangle 

ev_mm2flags  second  rectangle  event  flag 
ev_mm2x,  ev_mm2y,  ev_mm2width,  and  ev_mm2height 

these  parameters  define  the  location  and  size  of  the 
second  mouse  event  rectangle 


C Function  Reference  Guide  389 


ev_mgpbuff  a pointer  to  a 16-byte  buffer  to  hold  the  message  in  the 
case  of  a message  event 
ev_mtlocount  and  ev_mthicount 

the  low  and  high  words  of  a long  int^er  used  to  set  the 
number  of  milliseconds  to  wait  for  a timer  event 
ev-mmox  and  ev_mmqy 

the  X and  y coordinates  of  the  mouse  pointer  when  the 
mouse  event  occurred 

ev_mmobutton  the  state  of  the  mouse  buttons  when  the  event  occurred 

ev_mokstate  the  state  of  the  kqrboard  when  the  event  occurred.  The 

bits  have  the  following  meaning: 


Bit  0 right  shift 

Bit  1 left  shift 

Bit  2 Control  key 

Bits  Alternate  key 


ev_mkretum  kq^code  for  the  key  pressed  in  a keyboard  event 
ev_mbretum  the  number  of  times  the  mouse  buttons  entered  the 
desired  state 


The  function  returns  a value  with  the  bit  set  to  indicate  the  event 
that  had  occurred.  The  bit  representations  are  the  same  as  for  param- 
eter ev_mflags. 

WORD  evnt-timer  (ev_tlocount,  ev_thicount) 
unsized  WORD  ey^tlocount, 
ev-fhicount; 

Walt  for  a specified  amount  of  time  to  pass.  The  amount  of  time  is 
given  as  a long  int^er  value  to  Indicate  length  of  the  time  interval  in 
milliseconds.  The  long  integer  (four  b3d:es)  is  divided  into  the  unsigned 
WORD  (i.e.,  int)  values  of  two  bytes  each.  The  low  word  is  passed  in 
parameter  ev_tlocotmt  and  the  high  word  is  in  ev-thicount  The 
function  always  returns  a value  of  1. 


WORD  Fattrib  (£aame,  wflag,  attiibs) 
char  *fiiame: 

WORD  wflag; 

WORD  attribs; 


Get  or  set  the  file  attribute  bits.  The  file  is  specified  by  the  name  given 
by  fioame.  If  wflag  is  0.  the  file’s  current  attributes  are  returned.  If 
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wflag  is  1.  the  file’s  attributes  are  set  to  bit  settings  of  attribs  as 
follows: 


Bit Attribute 

0 Read  only 

1 Hidden 

2 intern 

3 11  byte  volume  label 

4 Subdirectory 

5 File  has  been  written  to  and  dosed 


WORD  Pclose  (fhandle) 

WORD  fhandle; 

Close  the  file  associated  with  fliandle.  0 Is  returned  if  successful; 
otherwise  an  error  value  Is  returned. 

WORD  Fcieate  (fiiame,  attribs) 
char  *fiaame; 

WORD  attribs; 

Create  a file  with  the  filename  fname  and  the  attributes  given  by 
attribs.  The  bits  of  attribs  have  the  following  meaning: 


Bit Description 

0 File  set  to  read  only 

1 File  hidden  from  directory  search 

2 FUe  set  to  SYSTEM 

3 File  contains  1 1 byte  volume  labd 


If  the  bit  Is  set  to  1,  the  file  has  that  attribute. 

The  function  returns  a write  only  nonstandard  handle  to  the  file, 
which  Is  a positive  number.  If  an  error  occurred,  a n^atlve  error  value 
Is  returned. 

VOID  Fdatime  (fliandle,  timeptr,  wflag) 

WORD  fliandle; 
long  *tim^tr; 

WORD  wflag; 

Get  or  set  the  date  and  time  stamp  for  a file.  The  fUe  Is  referred  by  Its 
handle  given  In  fliandle.  If  the  parameter  wflag  Is  0,  the  time  stamp  is 
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read  Into  timeptr.  If  wflag  is  1,  the  time  stamp  is  set  from 
The  high  WORD  of  the  value  at  timeptr  is  the  time  and  the  low  WORD 
is  the  date.  See  the  TgetdateO  and  TgettimeO  functions  for  the 
format  of  the  date  and  time  WORDS. 

WORD  Fdelete  (fiiame) 
char  ^foama; 

Delete  the  file  named  by  fiiame.  A returned  value  of  0 indicates  suc- 
cess; otherwise  a negative  error  number  is  returned. 

WORD  Pdnp  (fhandle) 

WORD  fliandle; 

Duplicates  a stemdard  handle.  A standard  handle  has  a value  from  0 
through  5.  The  handle  to  duplicate  is  given  by  parameter  fliandle.  The 
function  returns  a nonstandard  handle  or  a negative  error  number. 

WORD  Fforce  (stdh,  nonstdh) 

WORD  stdh, 

nonstdh; 

Force  the  standard  handle  stdh  to  point  to  the  same  file  or  device  as 
the  nonstandard  handle  nonstdh.  The  returned  value  is  0 if  success- 
ful; otherwise  an  error  number  is  returned. 

long  Pgetdta  ( ) 

Returns  the  address  of  the  current  Disk  Transfer  Area  (DTA)  used  by 
function  Psflntf ) eind  Psnestf ). 

WORD  Plopfint  (but  flUer,  drvno,  apt,  txackno,  sideno, 
interlv,  magic,  vix;^) 

WORD  »buf; 

long  flller; 

WORD  drvno,  apt,  trackno,  sideno, 

interlv,  virgin; 
long  magic; 

Format  one  track  on  a floppy  disk.  The  buffer  pointed  to  by  buf  must  be 
large  enough  to  hold  an  entire  track  Imeige  (8K  for  nine  sectors  per 
track).  Parameters  drvno,  qit,  trackno,  and  sideno  give  the  drive 
number  (0  or  1),  the  number  of  sectors  per  track  (usually  nine),  the 
track  number  (0  through  79),  and  the  side  number  (0  or  1 ).  respectively. 
The  parameter  filler  is  unused.  The  sector  interleave  factor  (usually  1 ) is 
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given  as  intedv.  TTie  value  for  magic  is  the  special  number  0x87654321. 
The  data  In  the  sectors  is  filled  with  the  value  In  virgin.  The  high  bit  of 
vitgin  must  not  be  set  and  the  value  0 should  be  avoided.  The  recom- 
mended viigin  value  is  0xE5E5. 

The  function  returns  0 if  successful,  or  a negative  error  value  if  not 
A null-terminated  list  of  bad  sector  numbers  (one  WORD  each)  is 
returned  in  the  buffer.  The  list  is  not  necessarily  in  numerical  order.  If 
no  bad  sectors  were  forind,  the  first  WORD  will  be  0. 

WORD  Iloprd  (buf;  filler,  dxvno,  sectno,  trackno,  sideno,  count) 
WORD  *bufi 
long  filler; 

WORD  drvno,  sectno,  trackno,  sideno,  count; 

Read  sectors  from  a floppy  disk.  The  function  reads  count  number  of 
sectors  into  the  word-aligned  buffer  pointed  to  by  but  Parameters 
drvno,  sectno,  trackno,  and  sideno  give  the  drive  nvimber  (0  or  1).  the 
sector  number  ( 1 through  9).  the  track  number  (0  through  79).  and  the 
side  number  (0  or  1).  respective^.  The  parameter  filler  is  unused.  The 
function  returns  0 if  successful,  or  a negative  error  value  if  not 

WORD  Flopver  (bu^  filler,  drvno,  sectno,  trackno,  sideno,  count) 
WORD  *bufi 

long  filler; 

WORD  drvno,  sectno,  trackno,  sideno,  count; 

Verify  a floppy  disk.  The  function  reads  count  number  of  sectors  from 
the  word-aligned  buffer  pointed  to  by  but  The  buffer  must  be  1,024 
bytes  in  length.  Parameters  drvno,  sectno,  trackno,  and  sideno  give  the 
drive  number  (0  or  1),  the  sector  number  (1  through  9).  the  track 
number  (0  through  79),  and  the  side  number  (0  or  1),  respectlvety.  The 
parameter  filler  is  unused. 

The  function  returns  0 if  successful,  or  an  negative  error  value  if  not 
A null-terminated  list  of  bad  sector  numbers  (one  WORD  each)  is 
returned  in  the  buffer.  The  list  is  not  necessarily  in  nvunerical  order.  If 
no  bad  sectors  were  found,  the  first  WORD  will  be  0. 

WORD  Flopwr  (buf,  filler,  dxvno,  sectno,  trackno,  sideno,  count) 
WORD  »bufi 

long  filler; 

WORD  drvno,  sectno,  trackno,  sideno,  count; 

Write  sectors  to  a floppy  disk.  The  function  writes  count  number  of 

sectors  from  the  word-aligned  buffer  pointed  to  by  but  Peirameters 
drvno,  sectno.  trackno,  and  sideno  give  the  drive  number  (0  or  1).  the 
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sector  number  (1  through  9),  the  track  number  (0  through  79),  and 
the  side  number  (0  or  1),  respective^.  The  parameter  filler  is  unused. 
The  function  returns  0 if  successful,  or  an  negative  error  value  if  not 

WORD  Popen  (fiiamet  mode) 
char  *fiiame; 

WORD  mode; 

Open  the  file  named  fiiame  with  the  access  set  to  mode.  The  access  msQr 
be  0 for  read  only,  1 for  write  only,  or  2 for  read  or  write.  The  function 
returns  a positive  nonstandard  handle  to  the  file.  A n^atlve  returned 
error  value  is  returned  on  an  error. 

WORD  fonn-alert  (fo-adeflrttn,  fo-astrlng) 

WORD  fo_adefbttn; 

<diar  *fo_ast>ing; 

Display  an  alert  box.  This  function  handles  the  drawing  and  interac- 
tion required  to  initialize  the  screen,  draw  the  alert  box,  allow  user 
interaction,  restore  the  screen,  and  report  the  exit  button  selected  to 
the  application.  Parameter  fo-adefbttn  specifies  the  default  exit  but- 
ton as  follows: 


0 No  defatdt  exit  button 

1 First  &dt  button 

2 Second  exit  button 

3 Third  exit  button 


Parameter  fo-astiiiig  points  to  a string  defining  the  format  for  the 
alert  box.  The  string  consists  of  three  sections.  E)ach  section  is  sur- 
rounded by  a set  of  square  brackets  ([  ]).  The  first  section  specifies  the 
icon  to  use  vdiere: 


0 No  icon, 

1 The  NOTE  icon, 

2 The  WATT  icon,  and 

3 The  STOP  icon. 


The  second  portion  of  the  string  contains  the  message  text  The  text 
may  consist  of  up  to  four  lines  of  32  characters  per  line.  To  signal  the 
end  of  a line  in  the  message  text  use  the  vertical  bar  ( | ) character. 

The  last  portion  of  the  string  contains  the  text  for  up  to  three  exit 
buttons  with  20  characters  each.  The  vertical  bar  ( | ) is  again  used  to 
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separate  the  text  for  each  button.  The  format  for  the  fo_astring 
parameter  Is  given  below: 

'‘{(Icon  ^))(  (message  test)]  [(exit  buttons))” 

The  function  returns  the  number  of  the  button  used  to  exit  the  alert 
box. 

WORD  form-center  (fo-ctree,  fo-cx,  fo-^,  fo-cw,  fo-di) 

OBJECT  *fo-ctree; 

WORD  *fo-cx.  *fo^,  *fo_cw,  *fb-clu 

Determine  the  coordinates  to  center  a dialog  box  on  the  screen.  The 
object  tree  for  the  dialog  box  is  pointed  to  by  fo-ctree.  Upon  return, 
fo-cz.  fo-^,  fo-cw,  and  fo-ch  define  the  position  and  size  of  a 
rectan^e,  centered  on  the  screen,  for  the  dialog  box.  The  function 
always  retvims  the  value  1. 

WORD  form-dial  (fo-diflag, 

fo-diUttlz.  fb-dllittty.  fodUittlw.  fo-dUittlh. 
fo-dfl>igs.  fo-dibixy.  fo-dibigw.  fo-dibigh) 

WORD  fo-diflag 

fb-dUittlz.  fo-dilittly.  fb-diUttlw.  fo-dOittlh, 
fo-dibigs,  fo-dibigy,  fo-diblgw,  fo-dibigh; 

Dialog  box  display  function.  This  function  performs  four  distinct 
operations  associated  with  displaying  a dialog  box.  First,  the  flmction 
can  reserve  space  for  the  dialog  box.  Second,  the  function  can  draw  an 
expanding  box.  Third,  the  function  can  draw  a shrinking  box.  And 
finally,  the  function  can  release  the  space  reserved  for  the  dialog  box. 
Only  the  first  and  last  of  these  operations  must  be  done  before  display- 
ing the  dialog  box. 

The  smallest  size  for  the  dialog  box  is  defined  by  fo-dilitdz,  fo-di- 
littly,  fo-dilittlw,  and  fo-dilittlh,  which  give  the  x and  y coordinates, 
width,  and  height  respectively.  The  largest  size  (and  the  size  used  to 
reserve  screen  space)  is  given  by  fo-dibigx,  fo-dibigy,  fo-dibigw,  and 
fo-dibigh  for  the  x and  y coordinates,  width,  and  height  respective^. 
All  coordinates  are  relative  to  the  screen. 

The  actual  operation  performed  is  specified  by  the  value  for  fo-diflag 
using  the  defined  constants: 


Constant 

Value 

Function 

FMD-START 

0 

Reserve  screen  space  for  dialog  box 

FMD-GROW 

1 

Draw  expanding  box 

FMD-SHRINK 

2 

Draw  shrinking  box 

FMD-FINISH 

3 

Release  reserved  space  and  cause  application  to 
redraw  screen 
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A returned  value  of  0 indicates  an  error. 

WORD  f6rm_do  (fo-dotree,  fo_dostartob) 

OBJECT  *l6-dotiee: 

WORD  fo-dostartob; 

Cause  the  Form  Manager  to  monitor  the  user’s  interactions  with  a 
form.  Parameter  fo-dotree  points  to  the  object  tree  containing  the 
form.  Paramenter  fo-dostartob  is  the  object  index  of  the  starting 
object  which  will  be  active  when  the  form  appears.  This  object  must  be 
an  editable  text  field.  A value  of  —1  indicates  that  the  form  does  not 
contain  an  editable  text  field.  When  form-do( ) is  called,  control  is 
passed  to  the  AES  until  the  user  creates  an  exit  condition  (see  text). 
The  function  returns  the  object  index  of  the  object  that  caused  the 
exit  condition. 

WORD  form-error  (fo-enum) 

WORD  fo-enum; 

Display  an  error  box.  This  is  a pre-defined  dialog  box  that  displays  a 
message  based  upon  the  error  number  specified  in  fo-enum.  GEMDOS 
has  predefined  numbers  representing  system  errors.  However,  these 
values  are  usualfy  returned  by  the  DOS  functions  as  negative  values  so 
the  application  must  use  the  absolute  value  of  the  returned  error 
value. 

The  value  returned  by  this  function  is  the  number  of  the  exit  button 
selected.  On  the  Atari,  only  one  exit  button  is  displayed  in  the  error 
box. 

long  Fread  (fliandle,  count,  buf) 

WORD  fliandle; 
long  count; 

char  *buf; 

Read  from  the  file  Indicated  by  fliandle.  The  number  of  b3rtes  to  read  is 
given  by  count,  and  the  data  is  placed  in  the  buffer  pointed  to  by  buf. 
The  actual  number  of  bytes  read  is  the  return  value.  A value  of  0 indi- 
cates the  end  of  file,  eind  a negative  value  is  an  error  value. 

WORD  Frename  (zero,  oldname,  newname) 

WORD  zero; 

rihar  *oldname, 

*newname; 

Rename  a file  from  oldname  to  newname.  The  new  name  of  the  file 
must  not  exist  on  the  disk.  The  new  file  may  be  in  another  directory. 
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The  parameter  zero  is  always  0.  A value  of  0 is  returned  if  successful; 
otherwise  an  error  number  is  returned. 

long  Fseek  (offiMt,  fliandle,  seekmode) 
long  ofGset; 

WORD  fliandle: 

WORD  seekmode; 

Set  the  current  file  pointer  position  with  the  file  specified  fliandle. 
The  ofbet  is  the  number  of  b}rtes  to  move.  The  seekmode  is  the  posi- 
tion from  which  to  count  the  offset.  The  seekmode  has  the  following 
values: 


Seekmode Offset  Start  Position 

0 From  the  beginning  of  the  file 

1 From  the  current  position 

2 Prom  the  end  of  the  file 


The  new,  absolute  pointer  position  is  returned. 

WORD  &eLJnpiit  (&_iinpafh,  &_iinsel,  fis_ieid>utlon) 
char  *&_ilnpatli, 

*fi}-iinsel; 

WORD  *&-ierinitton; 

Display  the  file  selector  dialog  box  and  allow  the  user  to  select  a file. 
This  function  handles  all  procedures  and  data  required  to  display  and 
manage  the  fUe  selector  dialog  box.  The  application  supplies  the 
default  search  path  in  string  &_Jinpath,  and  ^e  default  filename  in 
string  &-flnseL  Upon  return,  fis-iinpatfa  contains  the  search  path  set 
by  the  user,  and  fa.,  tinsel  contains  the  filename  sdected  by  Ihe  user. 
Parameter  &_iesbutton  is  set  to  the  exit  button  used,  where  0 is  the 
Cancel  button  and  1 is  the  OK  button.  A value  of  0 indicates  an  error 
has  occurred. 

VOID  Fsetdta  (addr) 
char  *addr; 

Set  the  Disk  Transfer  Area  (DTA)  to  the  memory  pointed  to  by  addr. 
The  DTA  is  used  only  by  function  Faflrstf ) and  Fanextf ) ). 


WORD  F^zat  (fiqiec,  atfaribs) 
char  *fapec; 
WORD  attribs; 
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Search  for  the  first  occurrence  of  the  file  given  by  &pec.  The  file  speci- 
fication may  contain  wildcard  characters  (?  emd  *)  In  the  filename, 
but  not  in  the  pathname.  The  bit  settings  of  attribs  determine  which 
files  are  located.  If  attribs  is  0,  only  “normal”  files  are  found.  The  bit 
settings  are: 


Btt Attribute 

0 Read  only 

1 Hidden 

2 System 

3 11  -byte  volume  label 

4 Sub^rectoiy 

5 File  has  been  written  to  and  closed 


When  the  file  is  located,  the  function  fills  the  Disk  Transfer  Area 
(DTA)  with  information  about  the  file.  The  DTA  is  a 44-byte  data 
structure  with  the  following  format* 


Byte 

Length 

Contents 

0 

20  bytes 

Reserved  for  OS 

21 

1 byte 

FUe  attributes  (as  above) 

22 

2 bytes 

FUe  time  stamp 

24 

2 bytes 

FUe  date  stamp 

26 

4 bytes 

FUe  size 

30 

14  bytes 

FUe  name  and  extension 

The  function  returns  0 if  a file  was  found;  otherwise  a negative  error 
number  is  returned. 

WORD  Fsneact  ( ) 

Search  for  the  nejrt  occurrence  of  a file.  The  search  parameters 
are  initially  set  by  Fsfirstf ).  If  a file  is  found,  the  DTA  is  filled  as  in 
Fsfirstf ).  The  function  returns  0 if  a file  is  found;  otherwise  an  error 
number  is  returned. 

long  Fwrite  (fliandle,  count,  bnf) 

WORD  fliandle; 
long  count; 

char  *bufl 

Write  the  data  from  the  memory  location  pointed  to  by  buf  to  the  file 
specified  by  fliandle.  The  number  of  bytes  to  write  is  given  by  count.  A 
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positive  value  returned  gives  the  number  of  bytes  actually  written.  A 
n^ative  value  is  an  error  number. 

BPB  *Getbpb  (drv) 
drv; 

Get  the  BIOS  Parameter  Block  (BPB)  of  the  drive  given  by  div.  The 
drive  numbers  are:  0 is  A.  1 is  B,  etc.  The  function  returns  a pointer  to 
the  BPB,  or  NULL  if  the  BPB  could  not  be  determined.  The  BPB  is 
defined: 


typedef  stnibt  bios-pb  { 
WORD  xecsiz,  /* 

dsiz,  /* 

dslzb.  /* 

rdlen,  /* 

fidze.  /* 

fotiec,  /* 

datiec,  /* 

numd,  /* 

bflags;  /* 

}BPB: 


pl^aical  sector  size  in  Iqrtes  (512)  */ 
duster  size  in  sectors  (2)  */ 
duster  size  in  bytes  (1024)  */ 
root  directory  lenglli  in  sectors  */ 
PAT  size  in  sectors  */ 
sector  * of  1st  sector  of  2nd  FAT  */ 
sector  * of  1st  data  sector  */ 

# of  data  dusters  on  disk  */ 
ila^  */ 


The  usage  of  the  BPB  and  its  contents  extend  bqrond  the  scope  of  this 
book.  Refer  to  the  GEMDOS  documentation  for  more  details. 


VOID  Getnqpb  (p-mpb) 

struct  nqib  *p_mpb; 

Get  a Memory  Parameter  Block  (MPB).  See  y^pendix  D.  System  Ad- 
dresses, for  information  on  the  nq>b  structure. 

WORD  Getrez( ) 

Return  the  screen's  current  resolution  as: 


0 Low  resolution  (320  X 200) 

1 Medium  resolution  (640  X 200) 

2 High  resolution  (640  X 400) 


long  Gettime( ) 


Return  the  current  date  and  time.  The  bits  in  the  long  value  retmned 
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have  the  following  interpretation: 


Bits 

Meaning 

0-4 

Seconds  divided  by  2 (0-29) 

5-10 

Minutes  (0-59) 

11-15 

Hours  (0-23) 

16-20 

Day  in  month  (1-31) 

21-24 

Month  (1-12) 

25-31 

Years  since  1980  (0-1 19) 

char  Giaocess  (data,  legno) 
char  data; 

WORD  r^BO; 

Access  the  registers  on  the  AY-3-8910  sound  chip.  The  register  to 
access  is  given  by  r^no.  If  regno  has  its  high  bit  set  (logically  ORed 
with  0x80),  the  function  writes  the  value  in  data  into  the  roister. 
Otherwise  the  function  returns  the  current  value  in  the  register.  See 
Chapter  6 for  details  regarding  sound  generation. 

The  sound  chip  is  used  by  the  operating  ^tem  for  other  functions. 
Therefore  a program  accessing  the  sound  chip  must  perform  its 
changes  uninterrupted.  This  function  provides  that  facility  and  should 
be  used. 

WORD  graf-dragboz  (gr_dwidth,  gr-dheight, 
gr-dstartz,  gr-dstaxty, 

gr-dboundz,  gr_dboundy,  gr-dboimdw,  gr_dboundh, 
gr_dfiiiisliz,  gr_ dfinidqr) 

WORD  gr_dwidtti,  gr-dhei^t, 
gr-dstarts,  gr_dstarty, 
gr_dbounx,  gr_dboundy, 
gr-dboimdw,  gr-dboundh, 

*gr  HflnlaliT,  *gr  iWtilaiiy; 

Allow  the  user  to  drag  a box  outline  on  the  screen.  When  this  func- 
tion is  called,  the  AE^S  places  a rectangle  outline  on  the  screen  with 
the  width  gr-dwidth  and  height  gr-dheight.  The  upper  left  comer  of 
the  outline  starts  at  coordinates  gr-dstarts  and  gr-dstarty.  Tlie  appli- 
cation can  limit  the  movement  of  the  drag  box  by  specifying  the 
boundary  rectangle  in  gr-dboundz,  gr-dbonntfy,  gr-dboundw,  and 
gr-dboundh.  When  the  user  releases  the  mouse  button,  the  func- 
tion puts  the  coordinates  of  the  upper  left  comer  into  parameters 
gr-dfinishz  and  gr.jdfiniahy.  A returned  value  of  0 indicates  an  error. 
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WORD  graflgrowboK  (gr-gste,  gr-gsly,  gr_gBt«vidfli,  gr-gstiieight. 
gr-gfinz,  gr-gfi]^,  gr_gfinwidth,  gr_gfiiihelght) 

WORD  gr_gBtz,  gr-^ly,  gr_gBtwidih,  gr-gsdieight, 

gr-gflnz,  gr_gGb7,  gr..gfinwiddi,  gr-gflnhelght; 

Draw  an  expanding  box  outline.  This  routine  places  a box  outline 
on  the  screen  at  the  location  and  size  given  gr-^tx,  gr_siy« 
gr-gstwidth,  and  gr-^theight.  The  box  then  expands  to  its  final  size 
and  location  given  by  gr-gflnx,  gr-gfiny,  gr-g^wldth,  and  gr-gfint' 
heiglit.  A returned  value  of  0 indicates  an  error. 

WORD  grafUiasidle  (gr_hwcl>ar,  gr-hhchar,  gr-liwboz,  gr-hhboz) 
WORD  *gr  Jiwdiar,  *gr-hhcJiar, 

*gr_hwboz,  *gr-hhl)ozt 

Request  the  handle  of  the  currently  open  physical  workstation  for  the 
screen  being  used  by  the  VDL  The  parameters  to  the  function  are  filled 
with  the  size  of  the  ^tem  font  characters  as  follows: 


gr-hwchar 

gr-hhchar 

gr_hwbox 

gr_hhbox 


the  width  of  the  character  cell 
the  height  of  the  character  cell 
the  width  of  a box  large  enough  to  hold  a system  font 
character 

the  height  of  a box  large  enough  to  hold  a system  font 
character 


All  of  the  above  values  are  measured  in  screen  pixels. 

WORD  grafLmbos  (gr-mwidHi,  gr-mhelght,  gr-msomces, 
gr-msourc^,  gr-mdestz,  gr-mdesty) 

WORD  gr-mwiddi,  gr-mhelght, 

gr-msonzcez,  gr-msourcey, 
g)r-mde8te,  gr_mdesty; 

Display  a box  outline  moving  from  one  location  to  another  on  the 
screen..  The  box  has  a set  size  given  by  gr_mwidth  and  gr-mhelght 
which  does  not  change.  The  starting  location  (of  the  upper  left  comer) 
is  given  by  gr_msourcex  and  gr-msourcey.  The  final  location  is  given 
by  gr_mdestK  and  gr-mdesty.  A returned  value  of  0 indicates  an  error. 

WORD  graC-inkstate  (gr-mkniz.  gr-mkmy,  gr-mkmstate, 
gr-mkkstate) 

WORD  *gr-mkmz.  *gr-mkiiiy, 

*^_inknistate,  *gr_mkkstate; 
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Obtain  the  current  mouse  location,  mouse  button  state,  and  k^oard 
state.  The  current  mouse  location  is  returned  through  peuameters 
gr_]nkiiuc  and  gr-mkmy.  The  button  state  is  returned  through  pa- 
rameter gr-mkmstate.  The  bits  of  this  value  indicate  the  position  of 
the  button  and  its  state.  If  the  bit  is  set  to  1,  the  button  is  currently 
down.  Bit  0 corresponds  to  the  furthest  left  button,  bit  1 is  the  second 
button  from  the  left,  and  so  on. 

The  kQlxiard  state  is  returned  through  parameter  gr-mkkstate. 
The  bit  settings  for  this  value  are: 


Bit 

Key 

0 

Right  shift 

1 

Left  shift 

2 

Control 

3 

Alternate 

If  the  bit  Is  set  to  1,  the  kqr  is  currently  being  pressed. 

This  function  always  returns  the  value  1. 

WORD  graf-moose  (gr-monumiber,  gr-mofieiddr) 

WORD  gr-monumher; 

MFORM  *gr_mo&ddT: 

Change  the  mouse  form.  This  function  tells  the  AES  which  mouse 
form  to  use.  The  mouse  form  is  given  by  the  value  in  gr_monumber 
based  upon  the  following  constants: 


Constant 

Value 

Shape 

ARROW 

0 

Arrow 

TEXT-CRSR 

1 

Text  cursor 

HOURGLASS 

2 

Bumble  bee 

POINT-HAND 

3 

Hand  with  pointing  finger 

FLAT-HAND 

4 

Open  hand 

THIN-CROSS 

5 

Thin  cross  hairs 

THICK-CROSS 

6 

Thick  cross  hairs 

OUTLN-CROSS 

7 

Outlined  cross  hairs 

USER-DEF 

265 

Form  defined  by  gr_mofaddr 

M-OFF 

256 

Turn  off  mouse  display 

M-ON 

257 

Turn  on  mouse  display 
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Calls  to  turn  the  mouse  display  on  or  off  may  be  nested.  Therefore 
each  call  to  turn  the  mouse  off  must  be  balanced  by  a call  to  turn  the 
mouse  on  before  It  will  reappear,  and  vice  versa. 

If  the  mouse  form  selected  is  USER—DEF,  the  function  refers  to  the 
mouse  form  definition  block  pointed  to  by  gr-mofaddr.  The  structure 
of  the  mouse  form  definition  block  is: 

typedef  struct  ni&tr  { 

WORD  mf  rfint; 

WORD  miLjdiot; 

WORD  mUnplanes; 

WORD  mUgf 
WORD  mL.bg; 

WORD  mf-mask[16]: 

WORD  mL.data{16]: 

} MFORM: 

The  fields  mf-shot  and  inL.3diot  define  the  hot  spot  of  the  mouse 
form.  The  hot  spot  is  the  point  the  AE^  uses  as  the  mouse  location. 
The  coordinates  are  measured  from  (0.0)  being  the  upper  left  comer. 
The  field  mfLnplanes  indicates  the  number  of  planes  in  the  form. 
Fields  tnf  fg  and  mL.bg  define  the  foreground  and  background  colors 
to  use  when  the  mouse  is  drawn  (see  raster  copy  functions  in  the  text). 
The  mfLmask  array  is  the  raster  for  the  mouse  form  mask  and  the 
mL-data  array  is  the  raster  to  the  mouse  form  itself. 

An  application  may  use  any  mouse  form  required  while  the  mouse  is 
located  within  the  top  window’s  work  area  However,  once  the  mouse 
leaves  this  work  area,  it  is  the  application's  responsibility  to  restore 
the  mouse  form  to  the  ARROW  or  HOURGLASS  as  £q)propriate.  The 
application  should  use  the  evnt_multi( ) function  to  detect  when  the 
mouse  enters  or  leaves  the  window's  work  area. 

A returned  value  of  0 indicates  an  error. 

WORD  grafLrubbetbox  (gr_nr,  gr-zy,  gr-xmlnwidth,  gr-rminbelght, 
gr-rlastwidth,  gr-rlastheigbt) 

WORD  gr-nc,  gr_iy, 

gr_nnit%fi\Afh^  gr  rmlnhel^ty 

*gr_rlastwldth,  *gr_lasChelght; 

Maintain  a “mbber  box”  on  the  screen.  A mbber  box  is  a rectangular 
outline  that  has  its  upper  left  comer  at  a fixed  location  (given  by  gr_ix 
and  gr_iy),  and  the  lower  right  comer  dragged  by  the  user.  While  the 
user  keeps  the  mouse  button  depressed,  the  AES  continues  to  track 
the  mouse  and  draw  the  mbber  box.  When  the  user  releases  the 
mouse  button,  this  function  returns  to  calling  application.  The  width 
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and  height  of  the  rubber  box  when  the  user  releases  the  mouse  button 
are  returns  through  parameters  gr_rlastwidCh  and  gr_rlastheight, 
respectively.  The  minimum  width  and  height  that  the  box  may  have  is 
passed  through  gr-nninwidtli  and  gr-rminheight.  A returned  value  of 
0 indicates  an  error. 

WORD  gra£_duiiiKboz  (gr-sfinx,  gr-sfiny,  gr_8^wldtli, 

gr-sfinheiglitt  gr_s8ts,  gr-ssty,  gr-sstwidth,  gr-ssfheight) 
WORD  gr-sfinz,  gr_8finy,  gr-sfinwidfh,  gr-aflnheight, 
gr-sstz,  gr_88ty,  gr-sstwiddi,  gr-sstheight; 

Draw  a shrinking  box  outline.  This  routine  places  a box  outline  on  the 
screen  at  the  location  and  size  given  by  gr_sfin2c,  gr-sfiny,  gr-sfin- 
width,  and  gr-^nheight.  The  box  then  shrinks  to  its  Anal  size  and 
location  given  by  gr-sstz,  gr_S8ly,  gr-sstwidtli,  and  gr-sstheight.  A 
returned  value  of  0 indicates  an  error. 

WORD  graf-sUdebow  (gr_slptree,  gr-slparent,  gr-slobfect,  gr-sl^) 
OBJEX}T  *gr_dptree: 

WORD  gr-slpaient, 
gr-slobtect, 
gr-shdi; 

Track  a sliding  box  within  its  parent  box.  When  the  user  selects  a slide 
box,  the  application  calls  this  function  to  track  the  user's  interactions. 
When  the  user  releases  the  mouse  button,  the  function  reports  the 
relative  position  of  the  slide  box  within  its  parent  The  slide  box  and 
its  slide  bar  must  be  objects  in  the  tree  pointed  to  by  gr_s^tree.  The 
slide  bar,  with  object  index  gr-s^aient.  must  be  the  parent  of  the 
slide  box,  object  index  gr-slotject  The  direction  of  tracking  is  set  by 
gr-^^ 


0 Horizontal 

1 Vertical 


The  value  returned  indicates  the  relative  position  of  the  slider 
within  its  parent  box.  This  value  will  range  from  0 to  1000.  For  hori- 
zontal sliders,  0 is  the  left  edge,  and  for  vertical  sliders,  0 is  the  top 
edge. 

WORD  graf-watchboz  (gr_wptree,  gr-wol^ect.  gr_winstate, 
gr-woutstate) 

OBJEXIT  *gr_wptiee; 

WORD  gr-wolgect. 

gr-winstate,  gr_woutstate; 
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Track  the  mouse  pointer  In  and  out  of  a predefined  box.  The  box  is 
the  rectangle  associated  with  a particular  object  The  object  tree  Is 
pointed  to  1:^  gr-wptree  and  the  object’s  index  is  given  by  gr-wo1^ect 
Tlie  state  of  the  object  while  the  mouse  pointer  is  inside  the  box  is 
specified  by  gr.winstate.  A returned  value  of  0 Indicates  an  error. 

The  state  of  the  object  when  the  mouse  pointer  is  outside  of  the  box 
is  specified  by  gr-wontstate.  The  states  are: 


Bit 

Constant 

Value 

NORMAL 

0x0000 

0 

SELECTED 

0x0001 

1 

CROSSED 

0x0002 

2 

CHECKED 

0x0004 

3 

DISABLED 

0x0008 

4 

OUTLINED 

0x0010 

5 

SHADOWED 

0x0020 

When  the  bit  is  set,  the  associated  state  is  active.  The  states  may  be 
combined.  The  NORMAL  state  indicates  no  bits  are  set 

VOID  Ikbdws  (cat,  ptr) 

WORD  cat; 

char  *ptr; 

Write  cat  bjrtes  from  the  string  at  ptr  to  the  intelligent  kej^ard  pro- 
cessor. The  cat  is  the  number  of  characters  to  write  minus  one. 

VOID  laitamas  (type,  paraaqi,  vec) 

types 

struct  param  *paiaaq>; 
iat  (*vec)  ( ): 

Initialize  the  mouse  packet  handler  of  the  intelligent  k^oard  device. 
This  function  interfaces  to  the  intelligent  keyboard,  which  is  beyond 
the  scope  of  this  book.  See  Atari  documentation  for  further  details. 
The  function  is  presented  here  for  reference.  The  parameter  usage  is: 


Type Is  the  Type  of  Operation  to  be  Performed  a& 

0 Disable  mouse 

1 Enable  mouse  in  relative  mode 

2 Enable  mouse  in  absolute  mode 

3 Unused 

4 Enable  mouse  in  keycode  mode 
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pniump  Points  to  a paiam  structure  (see  below) 

vcc  Points  to  a mouse  interrupt  handler  (see  kbdvbase( )). 


The  paxam  structure  contains: 

struct  param  { 

diar  topmode; 
char  Imttons; 
char  :q>aram; 
charyparam; 

WORD  xmax,  ymax; 

WORD  xlnitial.  yinitial; 

} 

where: 

topmode  determines  position  of  0 y coordinate 

0 = bottom  of  screen 

1 = top  of  screen 

button  parameter  for  intelligent  kQisoeird's  “set  mouse 
buttons”  command 

xparam  and  yp>aram  have  the  following  meanings 
depending  on  the  mode: 


Mode 

Meaning  of  xpamm  and  xpamm 

Relative 

Absolute 

KQ^de 

X and  y interrupt  threshold  values 
X and  y scale  factors 
X and  y delta  factors 

The  remaining  members  of  the  param  structure  are  used  in  absolute 
mode  only,  and  give  the  maximum  and  initial  x and  y coordinates. 

long  lorec  (devno) 

WORD  devno: 


Get  the  serial  device  input  buffer  descrlpter.  which  is: 


struct  iorec  { 

char  *buh 
WORD  ibu&ize. 
ibn&d, 
ibufU, 
ibuflow, 
ihnthigh; 

} 


/*  pointer  to  queue  */ 

/*  size  of  queue  in  bytes  */ 
/*  head  index  of  queue  */ 
/*  tail  index  of  queue  */ 

/*  low  data  mark  */ 

/*  hl^i  *^*>*‘^  mark  */ 
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The  function  returns  a pointer  to  the  input  buffer  descriptor  imme- 
diately followed  by  the  output  buffer  descriptor  (of  the  same  format). 

The  member  ibnfU  is  the  index  of  the  last  character  to  be  placed  in 
the  queue,  and  ibnfhd  is  the  index  of  the  last  character  to  be  removed 
from  the  queue.  The  queue  is  empty  if  ibnfhd  equals  ibuftL  The  ST 
requests  that  the  sender  stop  transmitting  when  the  number  of  char- 
acters in  the  queue  equals  ibufiiigb*  A request  to  the  sender  to  resume 
transmitting  is  given  when  the  number  of  characters  falls  below 
ibuflow.  Ihe  output  buffer  is  handled  in  a similar  manner. 

VOID  Jdisintfintno) 

WORD  intro; 

Disable  interrupt  number  intno  on  the  68901.  See  function  Bl^int( ) 
for  further  details. 

VOID  Jenabint  (intno) 

WORD  intno; 

Enable  interrupt  number  intno  on  the  68901.  See  function  M^int( ) 
for  further  details. 


long  Kbdvbase  ( ) 


Get  the  list  of  the  ^tem  vectors.  The  function  returns  a pointer  to  a 
structure  of  the  following  format 


struct  hbdvecs  { 

WORD(*midivec)(). 
(*ykbderr)  (). 
(«vmiderr)  ( ), 
(*vstatvec)  ( ), 
(*monsevec)  ( )« 
(*clockvec)  ( ), 
(*j<^vec)  ( ), 
(*midi^)  ( ), 
(•ikbdsysH); 

} 


/*  midi  input  */ 

/•  keyboard  error  *! 

I*  MIDI  error  */ 

/*  ikbd  status  packet  *! 
I*  mouse  packet  *! 

/*  clock  packet  */ 

/*  j;^ti(^  packet  */ 

/*  qnstem  BIIDI  vector  */ 
/*  intern  ikbd  vector  */ 


The  midivec  vector  is  initialized  to  a buffering  routine  in  the  BIOS. 
The  vkbderr  and  vmiderr  routines  are  called  whenever  an  overrun 
condition  is  detected  on  the  kQhoard  or  MIDI.  The  statvec,  mousevec, 
clockvec,  and  joyvec  point  to  the  ikbd  (intelligent  kqhoard)  status, 
mouse,  real-time  clock,  and  joystick  packet  handlers.  Ihe  midisys  emd 
ikbdsys  routines  are  called  when  characters  are  available. 
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WORD  Kbiate  (init,  xpt) 

WORD  init,  ipt; 

Get  or  set  the  kQdsoard  repeat  rate.  The  number  of  50  Hz  ticks  to  wait 
before  repeating  is  given  by  init  The  number  of  50  Hz  ticks  to  wait 
between  repeated  characters  is  given  by  ipt  If  either  parameter  is  — 1, 
that  value  is  not  changed. 

The  function  returns  the  previous  init  and  ipt  values  as  a WORD 
with  the  high  byte  containing  the  init  value  and  the  low  byte  contain- 
ing the  rpt  value. 

long  Kbshift  (mode) 

WORD  mode; 

Get  or  set  the  keyboard  shift  bits.  If  mode  is  negative,  the  current  set- 
tings are  returned.  If  mode  is  0 or  greater,  the  shift  bits  are  set  to  the 
low  8 bits  of  mode.  The  shift  bit  assignments  are  as  follows: 


m K^[ 

0 Right  shift 

1 Left  shift 

2 Control 

3 Alternate 

4 Caps  Lock 

5 Clr/Home  (right  mouse  button) 

6 Insert  (left  mouse  button) 

7 Reserved 


long  Kqrti>l  (unsbft,  sbft,  capslock) 

char  unshftl  ]•  shft(  ],  capsAock[  ]; 

Set  the  k^oard  translation  tables.  Each  parameter  is  a pointer  to  the 
base  of  an  array  of  128  characters.  These  tables  are  used  to  translate 
the  kqrstrokes  under  the  respective  conditiona  The  function  returns  a 
pointer  to  a structure  containing  the  three  parameters: 

struct  keytab  { 

char  *uiudilft; 
char  *shift; 
char  *capslock; 

} 


long  Logbasef ) 
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Returns  the  address  of  the  screen’s  logical  location  In  memoiy  Imme- 
dlatefy. 

long  Malloc  (amtmem) 
long  amtmem; 

Allocate  amtmem  bytes  of  memoiy.  The  function  returns  a pointer  to  a 
block  of  memoiy  containing  the  requested  number  of  tytes.  A returned 
value  of  NULL  Indicates  that  there  is  no  free  block  laige  enough  to 
meet  the  request 

If  amtmem  is  — IL,  the  function  returns  the  size  of  the  largest  free 
block  in  the  system. 

A process  may  not  have  more  than  20  blocks  allocated  by  Blalloc( ) at 
any  given  time. 

long  Mediadi  (div) 

WORD  div; 

Check  for  a media  change  on  a disk.  If  the  floppy  disk  has  been 
replaced,  the  media  change  will  be  true.  The  values  returned  Indicate 
the  following: 


0 Media  definite^  has  not  changed 

1 Media  might  have  changed 

2 Media  definitely  has  changed 


The  value  of  div  provides  the  drive  number  where  1 is  A.  2 is  B.  etc. 

WORD  meno-bar  (me-betree,  me-bdiow) 

OBJECT  *me_btree; 

WORD  me-bdiow; 

Displays  a menu  bar  if  me-bshow  is  TRUE  and  erases  the  menu  bar  If 
me-bshow  is  FALSE.  The  menu  bar  Is  the  object  tree  pointed  to  by 
me-btree.  An  sqiplicatlon  should  always  erase  the  menu  bar  before 
exiting  through  i^L.mdt( ).  A returned  value  of  0 Indicates  an  error. 

WORD  menu-icheck  (me_ctree,  me-dtem,  mc-ccbeck) 

OBJECT  *me_ctree; 

WORD  me-dtem, 

me-cdieck; 


Check  or  uncheck  a menu  item.  If  mc-cbeck  is  1.  the  check  mark  is 
displa}^  in  the  first  position  of  the  menu  item.  If  mc— check  is  0,  the 
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check  mark  is  removed.  Parameter  me-ctree  points  to  the  object  tree 
for  the  menu  and  me_citem  is  the  object  index  in  that  tree.  A 
returned  value  of  0 indicates  an  error. 

WORD  menu-ienable  (me_etree,  me-eitem,  me-eenable) 

OBJECT  *me_etree; 

WORD  me_eitem, 

me-eenabie; 

Enable  or  disable  a menu  item.  If  me-eenable  is  0,  the  menu  item  is 
disabled  emd  is  displayed  using  dimmed  characters.  If  me-eenable  is 
1,  the  menu  item  is  enabled.  Parameter  me-etree  points  to  the  object 
tree  for  the  menu  and  me-eitem  is  the  object  index  of  the  menu  item. 
A returned  value  of  0 indicates  an  error. 

WORD  menn-Tegister  (me-iepid,  me_xpstring) 

WORD  me-xepid; 

char  *me-iq>8tring: 

Register  a desk  accessory  with  the  AES.  When  a desk  accessory  is  first 
executed,  it  must  register  with  the  AES  to  be  shown  in  the  Desk 
menu.  The  accessory  uses  this  function  to  notify  the  AES  that  the 
application  with  ID  number  me-x^id  (from  the  iy>pl-init( ) function) 
is  to  be  placed  in  the  Desk  menu  with  the  name  given  in  me-xpstring. 
The  menu-xegistex( ) function  returns  a menu  item  ID  number  or  — 1 . 
A — 1 value  indicates  an  error,  usually  meaning  that  six  accessories 
are  already  in  the  Desk  menu. 

WORD  menu-test  (me-ttxee,  me_titem,  me-ttest) 

OBJEXDT  *me-ttree; 

WORD  me-titem; 

char  *me_ttext; 

Change  the  text  of  a menu  Item.  Parameter  me-ttxee  points  to  the 
object  tree  for  the  menu  and  me-titem  is  the  object  index  of  the  menu 
item.  The  next  text  is  pointed  to  by  me-ttest  The  new  text  must  be  no 
longer  than  the  length  of  the  original  text  in  the  menu.  A 0 returned 
value  indicates  an  error. 

WORD  menu-tnoxmal  (me_ntxee,  me-ntitle,  me_nnoxmal) 

OBJECT  *me-ntree; 

WORD  me-ntitle, 

me-nnoxmal; 

Set  a menu  title  to  normal  or  reverse  video  display.  If  me-noxmal  is  0, 
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the  menu  title  is  displayed  in  reverse  video.  If  me_nnonnal  is  1,  the 
menu  title  is  shown  in  normal  video.  Parameter  me_ntree  points  to 
the  object  tree  for  the  menu  and  me-ntitle  is  the  object  index  of  the 
menu  title.  A returned  value  of  0 indicates  an  error. 

VOID  MQ>int  (intemo,  yecptr) 

WORD  intemo, 

(*vecptr)  ( ); 

Set  the  68901  MFP  (Multi-Function  Peripheral)  Interrupt  number 
intemo  to  the  new  vector  vecptr.  The  old  routine  vector  is  written  over 
and  tmrecoverable  The  intermpt  numbers  are: 


Intem^jt Function 

0 Parallel  port  (Initially  disabled) 

1 RS232  carrier  detect  (initially  disabled) 

2 RS232  clear  to  send  (initial^  disabled) 

3 Unused,  disabled 

4 Unused,  disabled 

5 200  Hz  ^tem  clock 

6 Keyboard/MIDI  (6850) 

7 PoUed  iloppy/hard  disk  controllers  (initial^  disabled) 

8 Hsync  (Initially  disabled) 

9 RS232  transmit  error 

10  RS232  transmit  buffer  empty 

1 1 RS232  receive  error 

12  RS232  receive  buffer  empty 

13  Unused,  disabled 

14  RS232  ring  detect  (initially  disabled) 

15  Polled  monitor  type  (initially  disabled) 


WORD  Blfree  (saddr) 

long  saddr; 

Free  the  block  of  memoiy  starting  at  address  saddr.  The  block  of 
memory  must  have  been  previously  allocated  by  Malloc( ).  A value  of  0 
is  returned  if  successful;  otherwise  an  error  number  is  returned. 

VOID  Midiws  (cnt,  ptr) 

WORD  cnt; 

Char  *ptr; 


Write  a string  to  the  MIDI  port  Parameter  cnt  gives  the  number  of 
characters  to  write,  minus  one.  The  string  to  write  is  pointed  to  by  ptr. 
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WORD  Mwhriwfc  (zero,  baddr,  newsiz) 

WORD  zero: 

long  baddr, 

newaiz; 

Shrink  the  size  of  an  allocated  block  of  memory.  The  address  of  the 
block  is  ^ven  by  baddr.  The  new  size  is  specified  by  newsiz.  The  new 
size  must  be  less  than  the  current  allocation.  The  parameter  zero 
must  have  the  value  0.  The  function  returns  0 if  successful,  or  an  error 
number  if  not 

WORD  otjc-add  (ob^atiee,  ob-aparNit,  ob_achild) 

OBJECT  *ob_atree: 

WORD  ob_£q>arNit, 
ob.oidiild: 

Add  an  object  to  an  object  tree.  All  object  trees  in  the  AES  are  stored 
as  arrays.  Each  object  in  the  tree  is  placed  in  an  element  in  the  array. 
The  tree  is  created  1^  linking  the  objects  together.  This  function  adds 
the  object  at  index  ob-acfaUd  to  the  list  of  children  for  the  object  at 
ob-aparent.  The  parameter  ob-atree  points  to  the  object  tree  (base  of 
the  array).  A 0 value  returned  Indicates  an  error. 

WORD  otjc..chaiige  (ob-cfaree,  ob_cob|ect,  ob-creavd, 
ob_c»d4>»  ob_<7cl4>f  ob-cwd^,  ob_diclip, 
ob.cnew8tate,  ob-credraw) 

OBJECT  *ob_ctree: 

WORD  ob_co1^ect, 
ob-ciesvd, 

ob-candip,  ob_qrd^,  ob-cwcl^,  ob-diclip, 
ob-cnew8tate,  ob-ciedraw; 


Change  an  object’s  ob-ztate  field  in  the  OBJECT  structure  (see  text 
for  object  structures).  The  object  index  ob-cotject  in  the  tree  pointed 
to  by  ob-ctiee  has  its  ob-state  field  changed  to  the  value  in  ob-cncw- 
atate.  The  object  is  redrawn  if  ob-ctedtaw  is  1.  If  ob-crediaw  is  0.  the 
object  is  not  redrawn.  The  redraw  operation  is  limited  by  the  dipping 
rectangle  indicated  by  ob_cxd^,  ob-<7cli^,  ob^cwd^  and  ob-chcl4> 
for  the  X and  y coordinates,  width,  and  height,  respectivety.  A returned 
value  of  0 indicates  an  error. 

WORD  otjc-deletie  (ob_dltiee,  ob..dlobiect) 

OBJECT  *ob-dltree: 

WORD  ob-dlotject; 
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Delete  (unlink)  an  object  from  a tree.  The  tree  is  pointed  to  by 
ob.dltree.  The  starting  object  index  is  given  by  ob-dretartob.  The 
number  of  objects  to  draw  is  given  by  ob-dlobJecL  A returned  value  of 
0 Indicates  an  error. 

WORD  ot>jc-draw  (ob-drtiee,  ob_distartob,  ob-drdepth, 
ob_dnclip,  ob_diycl4>f  ob_drwclip,  ob-driiclip) 

OBJECT  *ob_dztiee; 

WORD  ob_dxstartob, 
ob-drdeptii, 
ob_dnEclip,  ob-diyclip, 
ob_diwclip,  ob-driicl4>i 

Draw  any  object  or  objects  in  an  object  tree.  The  object  tree  containing 
the  object(s)  is  pointed  to  by  ob-drtree.  The  starting  object  index  is 
given  by  ob-dxstartob.  The  number  of  objects  to  draw  is  given  by 
b_did^fli,  which  specifies  the  depth  of  levels  to  cover.  Level  0 is  the 
starting  object,  level  1 is  the  starting  object’s  children,  and  so  on.  TTie 
depth  specified  may  exceed  the  depth  of  the  tree  without  incident 
All  objects  are  drawn  within  a clipping  rectan^e.  The  upper  left 
comer  of  clipping  rectangle  is  given  by  ob-dixclip  and  ob-diydip. 
The  width  and  height  are  given  by  ob.diwd4>  and  ob-dibclip.  All 
coordinates  are  given  as  screen  coordinates. 

A returned  value  of  0 Indicates  an  error. 

WORD  ot^c-edit  (ob_edtree,  ob-jedobject,  ob-eddiar,  ob-edidz, 
ob-edkind,  ob-ednewidz) 

OBJECT  *ob_edtxee; 

WORD  ob_edo1^ect 
ob-eddiar, 
ob-edidz, 
ob-edidnd, 

*ob_ednewidz; 

Let  the  user  edit  the  text  of  an  object  The  object  index  is  ob_edob)ect 
in  the  tree  pointed  to  by  ob_edtree.  The  object  must  be  of  type 
G-TEXT  or  G_BOXTEXT  (see  text  for  descriptions  of  object  types  and 
object  stmctures).  The  character  entered  is  in  ob-edcfaar.  The  posi- 
tion (index)  of  the  next  character  in  the  text  string  is  in  ob-edidz.  The 
edit  function  to  perform  is  given  by  ob-edkind  using  the  following 
codes: 


0 Reserved 

1 Combined  values  In  the  te_ptext  and  te_ptmplt  fields  Into  a formatted 

string  and  turn  on  the  text  cursor 
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2 Validate  typed  characters  against  the  te-pvalld  held,  update  the  te-ptext 

field,  and  display  the  string 

3 Turn  off  the  text  cursor  


When  the  function  is  finished,  ob_ednewidx  contains  the  next 
character  position  in  the  text  string  after  the  edit  function  is  com- 
plete. A returned  value  of  0 indicates  an  error. 

WORD  otjc-find  (obJffree,  ob-&taitob,  ob-fdqptli,  ob_finz,  ob-fioay) 
OBJECT  *ob-ftiee; 

ob_&tartob, 
ob-Mepth, 
ob-fDoz,  ob-finy; 

Locate  an  object  at  a given  x and  y coordinate.  The  x and  y coordinates 
are  passed  in  ob-fimz  and  ob_£aqrt  and  are  screen  coordinates.  The 
tree  to  search  is  pointed  to  by  ob-ftree.  The  object  index  to  start 
searching  from  is  given  by  ob.&taitob,  and  ob-fdeptii  limits  the 
depth  of  the  search.  The  function  returns  the  object  index  of  the  object 
located  at  the  specified  position,  or  — 1 if  no  object  was  found. 

WORD  ol^c-offiiet  (ob_oflxee,  ob-ofol^ect,  ob-o&ofi;  ob_ofyoff) 
OBJECT  *ob-oftree; 

WORD  ob-ofotject, 

*ob-o&ofL  *ob-ofyoff; 

Convert  an  object’s  relative  coordinates  to  screen  coordinates.  The 
object  index  is  passed  in  ob_ofolject  and  the  tree  is  pointed  to  by 
ob-oftree.  The  screen  coordinates  are  returned  in  ob-ofirofF  and 
ohuofyatt.  A returned  value  of  0 indicates  an  error. 

WORD  ol^c^rder  (ob_oitree,  ob-orol^ect.  ob_oniewpos) 

OBJECT  *ob-ortiee: 

WORD  ob_orob|ect, 
ob-Axnewpos; 

Change  the  order  of  an  object  within  its  parent's  list  of  children. 
Parameter  ob-ortiee  points  to  the  object  tree  and  ob_orolject  is  the 
index  of  the  object  to  change.  The  new  position  is  specified  in  ob_ 
omewpos.  Hie  value  for  the  new  position  is: 


— 1 On  the  top 

0 On  the  bottom  (at  the  end) 

1 One  from  the  bottom 

2 Two  from  the  bottom 
etc. 
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VOID  OflQsibit  (bitno) 

WORD  bitno; 

Turn  off  bit  number  bitno  In  the  Port  A register  of  the  sound  chip. 
This  action  is  done  without  interruption  by  the  operating  system. 

VOID  Ongibit  (bitno) 

WORD  bitno; 

Turn  off  bit  number  bitno  in  the  Port  A register  of  the  sound  chip. 
This  action  is  done  without  interruption  by  the  operating  system. 

long  Pesec  (mode,  path,  cm^ttail,  environ) 

WORD  mode; 

long  cbar  *paQi,  *cmdtail,  *environ; 

This  function  performs  several  operations  based  upon  the  following 
value  in  mode: 


Mode 

Operation 

0 

Load  and  execute 

3 

Just  load 

4 

Just  execute 

5 

Create  the  base  page 

llie  path  is  the  filename  of  the  program  to  load.  The  cmdtail  is  the 
command  line  to  be  used  by  the  program.  The  environ  is  the  environ- 
ment string  to  placed  in  the  base  page.  If  environ  is  OL.  the  parent 
program's  environment  string  is  used. 

If  mode  is  0.  the  file  is  loaded,  the  base  page  is  created,  and  the 
program  is  executed.  The  fimction  returns  the  exit  status  of  the  child 
process. 

If  mode  is  3,  the  file  is  loaded  and  the  base  page  is  created.  The 
function  returns  the  address  to  the  base  page. 

If  mode  is  4,  path  is  the  address  of  the  base  page  and  the  program 
b^ins  executing. 

If  mode  is  5,  the  function  allocates  the  largest  free  block  of  memory 
for  the  child  process  and  creates  most  of  the  base  page.  The  text,  data, 
and  bss  size  and  the  base  values  are  not  setup.  The  parent  process  is 
responsible  for  maintaining  these  values. 

The  child  process  will  inherit  the  parent’s  standard  file  descriptors. 
Any  Pdiq>( ) or  Fforoe( ) calls  will  be  carried  over  to  the  child  process. 
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long  niysbaseO 

Returns  the  address  of  the  screen’s  physical  location  in  memoiy  at  the 
next  vertical  blank  Interrupt 

VOID  Protobt  (but  serialno,  disklype,  execflag) 
char  *bu^ 

long  serialno; 

WORD  didEtype,  execflag; 

Create  a prototype  boot  sector.  The  boot  sector  to  be  created  is  placed 
in  the  512  byte  buffer  pointed  to  by  bn£  The  serial  number  stamped 
into  the  boot  sector  is  given  by  serialno.  If  snlalno  is  — 1,  the  previous 
serial  number  is  used.  If  serialno  is  greater  than  0x01000000.  a ran- 
dom serial  number  is  used. 

The  disk  type  is  given  by  disktype  having  the  following  inteipreta- 
tlon: 


0 One  side.  180K.  40  tracks 

1 Two  sides.  360K.  40  tracks 

2 One  side.  360K.  80  tracks 

3 Two  sides.  720K.  80  tracks 


If  disktype  is  — 1 and  buf  points  to  an  existing  boot  sector,  the  disk 
iyp»e  information  remains  unchanged. 

The  executable  status  of  the  boot  sector  is  given  by  execflag.  A 0 
value  means  nonexecutable  and  a 1 value  means  executable.  A — 1 
value  with  a valid  boot  sector  in  buf  causes  no  change  to  the  execut- 
able status. 

VOID  Pterm  (retoode) 

WORD  retoode; 

Terminate  the  current  process,  dose  all  open  files,  and  release  any 
allocated  memoiy.  The  parameter  retcode  is  the  process’s  exit  code 
that  is  returned  to  the  parent  process. 

VOID  PtermOO 

Terminate  the  current  process  with  an  exit  status  of  0.  dose  all  open 
files,  and  rdease  all  memoiy  allocated  to  it  Source  file  must  indude 
OSBINDH. 
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VOID  Ptennies  (keq>cnt,  xetcode) 
long  keepcnt; 

WORD  xetcode: 

Terminate  the  current  process  and  keep  It  In  memoiy.  The  value  In 
keepcnt  determines  the  amount  of  the  program  to  retain  in  memory. 
An  memoiy  requested  and  allocated  by  the  program  is  not  released. 
The  value  of  xetcode  is  the  exit  code  returned  to  the  parent  process. 

VOID  Puntaes  () 

This  function  causes  the  system  to  reboot  without  loading  the  AES  or 
the  GEM  Desktop.  If  the  ^tem  is  in  ROM  (Read  Onfy  Memoiy).  this 
fimctlon  does  not  work.  If  this  function  had  already  been  called,  it 
simpty  returns  to  the  calling  program. 

long  Random  () 

Return  a 24-blt  random  number.  The  following  algorithm  is  used: 

S = (S  * C)  + K 

where  K is  1.  C is  3141592621,  and  S is  the  seed.  The  initial  value  for 
S is  taken  from  the  ^tem  variable  -firdock. 

WORD  xc-intexsec^l,  p2) 

GRECT  *pl,  *p2; 

Find  the  intersection  of  two  rectangles.  Each  parameter  refers  to  a 
GREXDT  structure  which  holds  the  values  for  an  AES  rectangle  (x,  y, 
width,  and  height).  The  function  calculates  the  rectangle  formed  by 
the  intersection  of  pi  and  p2.  The  intersecting  rectangle  is  returned 
through  p2.  Tlie  function  returns  TRUE  if  the  rectangles  intersect: 
otherwise  FALSE  is  returned. 

VOID  Rsconf  (qieed,  flowed,  oex,  xax,  tax,  acx) 

WORD  speed,  flowed,  ucx,  zsr,  tax,  sex; 

Configure  the  RS232  port  The  baud  rate  is  set  by  speed  as  follows: 


Speed  Baud  Rate 

0 19200 

1 9600 

2 4800 
(continued) 
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Speed 

Baud  Rate 

3 

3600 

4 

2400 

5 

2000 

6 

1800 

7 

1200 

8 

600 

9 

300 

10 

200 

11 

150 

12 

134 

13 

110 

14 

75 

15 

50 

The  flow  control  is  determined  by  flowctl  as  follow^: 


Fiotjodl 

Type  of  Flow  Control 

0 

No  flow  control  used  (default) 

1 

XON/XOFF 

2 

RTS/CTS 

3 

Both  XON/XOFF  and  RTS/CTS 

The  remaining  parameters  set  the  hardware  registers  for  the  68901 
MFP  (multifunction  peripheral).  Any  parameter  may  be  — 1 to  avoid 
setting  the  hardware  roister.  Only  the  ucr  parameter  Is  useful  Its  bits 
have  the  following  meanings: 


Bit  in  ucr Meaning 

0 Not  used 

1 Parity: 

0 = odd 

1 = even 

2 Parity  enable: 

0 = off 

1 = on 

3 and  4 Number  of  start/stop  bits: 


Bit  4 

Bit  3 

Start 

Stop 

Format 

0 

0 

0 

0 

Synchionous 

0 

1 

1 

1 

Asynchronous 

1 

0 

1 

1.5 

A^chronous 

1 

1 

1 

2 

As^chronous 

(continued) 
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Bit  in  ucr 

Meaning 

5 and  6 

Word  length: 

Bite 

Bits 

Word  length 

0 

0 

8 bits 

0 

1 

7 bits 

1 

0 

6 bits 

1 

1 

5 bits 

7 

Clock  mode: 

0 

= full  speed 

1 

= 1/16  rate  (recommended) 

WORD  mc-free  () 

Fliee  the  memoiy  space  allocated  to  the  resource  file  of  an  application. 
This  function  should  be  called  prior  to  exiting  the  application.  A 
returned  value  of  0 indicates  an  error. 

WORD  rsrc-gaddr  (re_gtype,  re_gindex,  re_gaddr) 

WORD  re_g(ype, 

re_glndex; 

char  **re_gaddr; 

Locate  the  address  of  the  data  structure  requested.  Hie  address  of  the 
data  structure  Is  returned  through  parameter  re-^ddr,  which  is  a 
pointer  to  a pointer  that  references  the  appropriate  data  structure. 
Hie  index  of  the  data  structure  within  the  object  tree  is  given  by 
le-glndez.  The  type  of  structure  to  search  for  is  given  by  le-gtype 
using  the  followiiig  predefined  constants: 


Constant 

Value 

Structure 

R-TREE 

0 

tree 

R_OBJECT 

1 

OBJECT 

R_TCDINPO 

2 

TEDINFO 

R-ICONBLK 

3 

ICONBIJC 

R_BITBIiC 

4 

BriBLK 

R_STRING 

5 

string 

R.JMAGEDATA 

6 

image  data 

R_OBSPEC 

7 

ob_spec  field  of  OBJECT 

R_TEPra2cr 

8 

te_ptext  field  of  TEDINFO 

R_TEPTMPLT 

9 

te_ptmplt  Add  of  TEDINFO 

R_TEPVAUD 

10 

te_pvaUd  Add  of  TEDINFO 

R-IBPMASK 

11 

Ib-pmask  Add  of  ICONBIJC 

R_IBPDATA 

12 

Ib-pdata  Add  of  ICONBIiC 

R_IBPraXT 

13 

Ib-ptext  Add  of  ICONBLK 

R_BIPDATA 

14 

bl_pdata  Add  of  BITBLK 

R_FRSTR 

15 

address  of  pointer  to  a free  string 

F_FRIMG 

16 

address  of  pointer  to  a free  image 
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The  function  returns  a 0 if  an  error  has  occurred. 

WORD  xsrc-load  (re  Jpfiiame) 
char  *re-lpfioame 

Load  a resource  file  Into  memory.  This  function  loads  the  resource  file 
named  by  re-lpfiiame  into  memory.  The  function  allocates  the 
memory,  loads  the  file,  adjusts  the  data  to  link  all  pointers,  and  makes 
the  data  available  to  the  application.  A retvimed  value  of  0 indicates  an 
error. 

WORD  rsrc-obfix  (re-otree,  re_oobject) 

OBJECT  *re_otree; 

WORD  re-oot{|ect; 

Convert  an  object's  location  and  size  from  character  coordinates  to 
pixel  coordinates.  The  character  coordinates  are  defined  as  the  object's 
X,  y,  width,  and  height  values.  Each  value  is  stored  as  a WORD  which 
has  a Least  Significant  Byte  and  a Most  Significant  Byte.  The  Least 
Significant  Byte  contains  the  character  position  of  the  value.  The  Most 
Significant  Byte  contains  the  positive  or  negative  pixel  offset  from  that 
character  position. 

The  index  of  the  object  is  given  re.oobject  in  the  tree  pointed  to 
by  re_otree.  The  function  always  returns  the  value  1. 

WORD  rsrc_saddr  (re_stypeL  re_sindez,  re-saddr) 

WORD  re.stypet 

re-slndez; 
char  *re_saddr; 

Set  the  address  of  a data  structure.  The  address  of  the  data  structure 
is  given  by  re_saddr  which  may  be  a pointer  to  the  data  structure 
itself.  The  index  at  which  the  address  is  stored  is  given  by  re-stndeac. 
The  type  of  structure  to  store  is  given  by  le-gtype  using  the  following 
predefined  constants: 


Constant  Value  Structure 


R-TREE  0 

R_OBJECT  1 

R-TEDINPO  2 

R-ICONBLK  3 

R_BITBIJC  4 

R-STRING  5 

R-IMAGEDATA  6 

R-OBSPEC  7 

R_TEPTEXT  8 


tree 

OBJECT 

TEDINFO 

ICONBLK 

BITBLK 

string 

Image  data 

ob_spec  field  of  OBJECT 
te_ptext  field  of  TEDINFO 

(continued) 
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Constant 

Value 

Structure 

R_TEPTMPLT 

9 

te-ptmplt  field  of  lEDINFO 

R-TEPVALID 

10 

te-pvalld  Add  of  TEDINFO 

RJBPMASK 

11 

ib-pmask  Add  of  ICONBliC 

RJBPDATA 

12 

ib-pdata  Add  of  ICONBLK 

RJBPTEXT 

13 

Ib-ptext  Add  of  ICONBLK 

R-BIPDATA 

14 

bi-pdata  Add  of  BITBLK 

R-FRSTR 

15 

address  of  pointer  to  a free  string 

F-FRIMG 

16 

address  of  pointer  to  a free  image 

The  function  returns  a 0 if  an  error  has  occurred. 

long  Rwabs  (rwflag.  bof;  count,  fecno,  drv) 

WORD 

char  *bub 

WORD  count,  xecno,  drv; 

Read  or  write  a logical  sector  on  a device.  This  function  returns  0 if 
successful;  otherwise  a negative  error  value  is  returned.  The  parame- 
ters are  used  as  follows: 


rwflag  determines  the  read/write  mode  as: 

0 Reeid 

1 Write 

2 Read,  but  do  not  affect  media  change 

3 Write,  but  do  not  affect  media  change 

buf  points  to  the  buffer  to  read  or  write  (buf  maQr  be  an  odd 

address,  but  it  will  be  slow) 
count  is  the  number  of  sectors  to  transfer 

recno  is  the  starting  logical  sector  number 

drv  is  the  drive  device  number  wdiere: 

0 Floppy  drive  A 

1 Floppy  drive  B 

> 1 Hard  disks,  networics,  or  other  devices 


VOIDScrdnipn 

Transfer  the  screen  image  to  the  printer.  This  function  onfy  worirs 
with  the  monochrome  monitor  and  Atari-compatible  printers. 

WORD  sop-read  (sc-ipscnq») 
char  *sc-jpsoap: 

Read  the  current  scrs^  directory  on  the  clipboard.  This  function  reads 
the  scrap  directory  and  places  the  data  found  into  the  buffer  pointed 
to  by  sc-xpsoap.  This  function  returns  a 0 if  an  error  has  occurred. 
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WORD  8Cip_.write  (sc-wpsctap) 
duur  *sc-wpscrap; 

Write  to  the  current  scrap  directory.  This  function  writes  the  data 
from  the  buffer  pointed  to  by  sc-wpscnq)  into  the  current  scrap  direc- 
tory. Only  one  scrs^  directory  file  is  available;  therefore,  writing  to  the 
scrap  directory  writes  over  an  previous  data  located  there.  This  func- 
tion returns  a 0 if  an  error  condition  exists. 

long  Setezc  (vecnum,  vec) 

WORD  vecnum; 

WORD  (*vec)  0; 

Change  one  of  the  exception  vectors.  The  vector  to  change  Is  given  by 
vecnum  and  the  address  of  the  new  routine  is  given  by  vec.  If  vec 
equals  — IL,  no  change  is  made  to  the  vector.  The  function  returns  the 
previous  vector  routine  address,  or  — 1 if  the  vector  could  not  be  set. 
The  vectors  used  by  the  ST  are: 


0x0000  to  OxOOFF 
0x0100 
0x0101 
0x0102 

0x0103  to  0x0107 
0x0200  and  above 


Reserved  for  the  68000 
GEMDOS  ^tem  timer  interrupt 
GEMDOS  critical  error  handler 
GEMDOS  process  termination 
GEMDOS  reserved 
Reserved  for  OEM  usage 


Refer  to  the  GEMDOS  and  Motorola  68000  documentation  for  further 
information  about  interrupts  and  vectors. 

WORD  Setcolor  (cdomum,  colorset) 

WORD  colomum,  coloTset; 

Change  the  color  of  a single  color  palette  entry.  The  palette  entry  to 
change  is  given  by  colomum.  The  new  color  is  determined  ty  the  bit 
settings  in  colorset  (see  text).  If  colorset  is  negative,  the  entry  is  not 
changed.  The  function  returns  the  previous  color  setting  for  the  entry. 

VOID  Sctpalette  (newpalette) 

WORD  *newpalette; 

Set  the  Atari  ST  color  palette.  The  parameter  newpalette  points  to  an 
array  of  16  WORDs  containing  the  16  entries  for  the  new  color  palette. 
The  new  palette  is  set  at  the  next  vertical  blank  interrupt 
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WORD  Setprt  (config) 

WORD  con^: 

Sets  the  printer  configuration  to  the  bit  settings  In  config.  If  config  Is 
— 1,  the  settings  are  not  changed.  The  function  returns  the  previous 
printer  configuration. 

The  bit  settings  have  the  following  Interpretation: 


Bit 

When  = 0 

When=  1 

0 

Dot  matrix 

Daisywheel 

1 

Color 

Monochrome 

2 

Atari  printer 

“Epson”  printer 

3 

Draft  mode 

Fl^  mode 

4 

Parallel  port 

RS232  port 

5 

Continuous  form 

Single  sheet 

6-14 

15 

Reserved 
Must  always  be  0 

VOID  Setscreen  (log-loc,  phjs-loc,  rez) 
char  *log-loc,  *phyB_loc; 

WORD  rez: 

Set  the  logical  screen  address,  the  physical  screen  address,  and  the 
ph3^1cal  screen  resolution.  Parameter  log-loc  contains  the  address  of 
the  new  logical  screen  location,  and  plqrB-loc  has  the  address  of  the 
new  physical  screen  location.  The  resolution  Is  set  to  the  value  In  rez. 

The  logical  screen  location  Is  set  Immediately,  whereas  the  physical 
screen  location  does  not  change  until  the  next  vertical  blank  Interrupt 
When  the  resolution  is  changed,  the  screen  is  cleared,  the  cursor  Is 
put  at  the  home  position  (upper  left),  and  the  VTS2  terminal  emulator 
is  reset 

If  any  parameter  has  a n^atlve  value,  that  parameter  is  Ignored. 
Therefore,  it  Is  possible  to  set  any  one  or  two  values  with  this  function. 

VOID  Settime  (datetime) 
long  datetime; 

Set  the  current  date  and  time.  The  bits  In  datetime  have  the  following 
interpretation: 


Bits Meaning 

0-4  Seconds  divided  by  2 (0-29) 

5-10  Minutes  (0-59) 

1 1-15  Hours  (0-23) 


(continued) 
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Bits 

Meaning 

16-20 

Day  in  month  (1-31) 

21-24 

Month  (1-12) 

25-31 

Years  since  1980  (0-119) 

WORD  shel-envm  (sh-spvalue,  sh-eparm) 
char  **ah_q>value,  *sh_q>arm: 

Seeut:h  in  the  environment  settings  for  the  occurrence  of  an  environ- 
ment parameter  string.  The  string  to  search  for  Is  pointed  to  by 
sh-eparm  (this  Includes  the  “=”  character).  The  address  of  the  byte 
Immediately  foUowlng  the  parameter  string  Is  returned  through 
sh_spvalue.  This  function  al'ways  returns  the  value  1. 

WORD  shel-find  (sh-^bufif) 
char  *sh-4>bu£^ 

Search  for  a filename  In  the  current  directory  and  In  each  directory  In 
the  search  path.  The  filename  to  search  for  Is  given  by  sh-ipbufif.  If 
the  file  Is  found,  sh-fybuff  Is  returned  with  the  full  GEMDOS  file  spec- 
ification. The  buffer  used  to  hold  the  file  name  must  be  at  least  80 
characters  long.  The  returned  value  of  0 Indicates  an  error. 

WORD  shcL-read  (idi-ipcmd,  sh-xptail) 
char  *sh-ipcmd,  *sh_iptaill: 

Let  an  application  Identify  the  command  that  Invoked  It  The  com- 
mand used  to  Invoke  the  application  Is  pointed  to  by  sh_ipcmd.  The 
command  tall  buffer  Is  pointed  to  by  sh-iptail.  The  command  tall 
buffer  has  the  following  format 


WORD  Address  of  environment  string 
pointer  To  command  line 

pointer  To  default  File  Control  Block 

pointer  To  second  default  F^e  Control  Block 


The  function  returns  a 0 If  an  error  occurred. 

WORD  sheL-write  (sh-wdoex,  sh_wisgr,  sh_wiscr, 
sh-wpcmd,  sh_wptail) 

WORD  sh-wdoez,  sh-wisgr,  sh_wiscr; 

char  *sh-wpcmd,  *sh.wptail; 
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Tell  GEM  AES  whether  to  run  another  application.  The  parameter 
sh—wdoex  Instructs  the  AES  to  exit  to  the  Desktop  or  run  another 
application  when  the  user  exits  the  current  application.  The  following 
flags  are  used; 

0 = exit  to  Desktop 

1 = run  another  application 

Parameter  sh-wisgr  tells  the  AES  whether  the  next  application  is  a 
graphic  application  as  follows: 

0 = not  graphic  application 

1 = grsq}hlc  application 

Parameter  sh-wiscr  tells  the  AES  whether  the  next  application  Is  a 
GEM  application  as  follows: 

0 = not  GEM  application 

1 = GEM  application 

The  parameters  sh-wpcmd  and  sh-wptail  provide  the  name  of  the 
next  application  and  Its  command  tall,  respectively. 

The  function  returns  a 0 If  an  error  has  occurred. 

long  Siq>er  (stac^tr) 

WORD  *stac^tr; 

Change  the  supervisor  mode  of  the  68000  processoty.  If  stadqttr 
equals  — IL,  the  function  is  inquiring  about  the  status  of  the  proces- 
sor. A returned  value  of  0 means  the  processor  Is  In  user  mode,  and  a 
value  of  1 means  the  processor  is  in  supervisor  mode. 

Otherwise  the  function  toggles  the  processor  between  user  and 
supervisor  modes.  If  the  processor  Is  in  user  mode,  the  processor  is 
put  into  supervisor  mode  and  the  new  stack  is  at  the  address  In 
parameter  stac^tr.  If  stack  equals  0,  the  supervisor  stack  location 
remains  the  same. 

If  the  processor  Is  in  supervisor  mode,  it  is  placed  Into  user  mode 
and  the  stack  location  changes  to  the  address  held  in  parameter 
staclq>tr  (or  remains  the  same  if  stack  equal  0).  When  returning  to 
user  mode,  the  stack  location  should  be  reset  to  the  location  used 
prior  to  entering  supervisor  mode.  The  stack  location  must  be  restored 
to  Its  original  location  before  the  process  terminates. 


VOID  Stqiesec  (codeptr) 

WORD  (*codeptr)  (); 
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Quick  entry  to  supervisor  mode.  The  function  places  the  68000  Into 
supervisor  mode  and  begins  executing  the  code  at  location  codeptr. 
When  the  routine  at  codeptr  returns,  the  68000  is  put  back  to  user 
mode,  and  the  program  continues  from  the  8iqiesec( ) call. 

Note:  the  code  at  codeptr  cannot  perform  BIOS  or  GEMDOS  calls. 
This  function  is  useful  for  quick  changes  to  protected  memory  loca- 
tions and  hardware  functions. 

WORD  Sversion  0 

Get  the  version  number  of  GEMDOS.  The  high  byte  contains  the 
minor  version  number  and  the  low  l^e  the  major  version  number. 

WORDTgetdate  () 

Return  the  current  date  in  the  following  format: 


Bits  Data 


0-4  The  day  ranging  from  1 to  31 

5-8  The  month  ranging  from  1 to  12 

9-15  The  year  since  1980  ranging  from  0 to  1 19 


WORD  Tgettime  0 

Return  the  current  time  of  day  in  the  following  format: 


Bits Data 

0-4  Seconds  divided  by  2 ranging  from  0 to  29 
5-10  Minutes  ranging  from  0 to  59 
1 1-15  Hours  ranging  from  0 to  23 


longTickcalO 

Return  the  S3retem  timer  calibration  value  to  the  nearest  millisecond. 
Generally  a useful  function  because  the  number  of  elapsed  millisec- 
onds is  passed  on  the  stack  when  a system  timer  exception  occurs. 


WORD  Tsetdate  (newdate) 
WORD  newdate; 
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Set  the  current  date.  The  value  returned  is  0 If  GEMDOS  accepted  the 
date  (although  Februaiy  31  may  be  accepted);  otherwise  an  error  value 
is  returned.  The  parameter  newdate  follows  the  format  described  in 
function  Tgetdate( ). 

WORD  Tsettime  (newtime) 

WORD  newtime; 

Set  the  current  time.  A value  of  0 is  returned  if  GEMDOS  accepted  the 
time;  otherwise  an  error  value  is  returned.  The  format  of  parameter 
newtime  is  the  same  as  that  described  in  Tgettime( ). 

WORD  v_aic  (handle,  x,  j,  radius,  begang,  endang) 

WORD  handle, 

X,  7,  rad, 
bqgang,  endang 

Draw  a circular  arc.  The  center  of  the  circle  is  placed  at  coordinates 
(x,y)  and  the  radius,  rad,  is  measured  along  the  x axis.  The  arc  starts 
at  the  2ingle  begang  and  proceeds  counterdockwise  to  angle  endang. 
The  parameters  measure  angles  in  tenths  of  a degree  and  can  range 
from  0 through  3600. 

WORD  v_bar  (handle,  pjqrairay) 

WORD  handle, 

p;yaiTay[4l; 

Draw  a filled  rectangular  area.  The  rectan^e  is  given  ty  array  pxyaxxay. 
The  current  fill  area  attributes  are  used.  As  opposed  to  the  'VT_recfl( ) 
function,  the  perimeter  is  drawn  based  upon  its  current  setting. 

WORD  v_bit-image  (handle,  filename,  paq[>ect,  z-scale,  y^scale, 
h align,  v_allgn,  i^axn^) 

WORD  handle: 

char  ^filename; 

WORD  paspect, 

z-scale,  7-scale, 
h_align,  v_align, 
zyarray: 

Output  bit  image  file.  This  function  allows  an  application  to  print  a bit 
image  file  (file  type  . IMG)  on  the  printer.  The  file  to  print  is  specified 
by  its  file  name  in  string  filename. 

The  bit  image  file  contains  the  pixd  sizes,  and  the  printer  driver  is 
able  to  calculate  a pixd  aspect  ratio.  Usli^  the  aspect  ratio  means  that 
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Images  retain  the  vertical  and  horizontal  relationship  that  appeared 
on  the  original  device.  For  example,  a circle  on  the  original  device 
appears  as  a circle  on  the  printer.  If  the  aspect  ratio  is  not  used,  the 
relationship  may  not  be  retained.  Parameter  paspect  controls  the  use 
of  the  aspect  ratio,  where  a value  of  1 means  retain  the  ratio,  and  0 
means  ignore  the  ratio. 

The  size  of  the  x and  y axes  are  probabfy  not  the  same  on  the  printer 
as  they  were  on  the  original  device.  This  function  allows  the  applica- 
tion to  specify  whether  fractional  or  integral  scaling  are  used.  Frac- 
tional scaling  ensures  that  the  corresponding  axis  fits  exactly  within 
the  scaling  rectan^e.  Integral  scaling  does  not  guaurantee  this,  but  is 
generally  faster.  The  parameters  s_scale  and  v-scale  determine  the 
type  of  scaling  for  each  axis.  A value  of  1 indicates  Integral  and  0 
indicates  fractional  scaling. 

Parameters  h and  v_align  determine  horizontal  and  vertical 
alignment  as  follows: 

h_allgn  = 0:  left 

1:  center 
2:  right 

V-align  = 0:  top 

1:  middle 
2:  bottom 


The  scaling  rectangle  is  optional.  It  is  speclfled  through  array  xyar- 
ray.  The  scaled  bit  image  always  resides  within  the  scaling  rectan^e.  If 
a combination  of  preserved  pixel  aspect  ratio,  scaling,  or  alignment 
causes  the  scaled  bit  image  to  extend  beyond  the  edge  of  the  scaling 
rectangle,  the  VDI  dips  the  bit  image  to  that  edge. 

WORD  ▼-ceUanay  (handle,  payarray,  row-length,  el-used, 
num-rowB,  wit-mode,  colanay) 

WORD  handle, 

pJ^BJCtaytdl, 

row-len^,  ^used,  num-iows,  wrt-mode, 
colarray[num-iow8  * eL-used]; 

Draw  a cell  array.  The  function  draws  a rectangular  array  within 
the  rectangle  given  by  psyarray.  The  rectangle  is  divided  into  cells 
based  upon  the  number  of  rows,  num-rows,  and  number  of  columns, 
row-length.  The  color  index  array,  colarray,  determines  the  color  of 
each  cell.  The  parameter  el-used  determines  the  number  of  elements 
per  row  in  colarray. 

If  the  device  does  not  support  ceU  arrays,  the  device  outlines  the  area 
with  a solid  line.  This  function  is  not  required  and  may  not  be  avail- 
able on  all  devices. 
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WORD  v-cirde  (handle,  z.  y,  xad) 

WORD  handle, 
z,y,  latU 

Draw  a circle.  The  center  of  the  circle  is  a coordinate  (z,y).  The  radius, 
rad,  of  the  circle  is  measured  along  the  x axis.  Fill  area  attributes  are 
used. 

WORD  v-clear_disp-Ust  (handle) 

WORD  handle; 

Clear  displt^r  list  This  function  clears  the  output  display  list  for  the 
printer.  It  is  similar  to  the  T-clrvdcl ) function  except  that  a form 
advance  is  not  incurred. 

WORD  v.clrwk  (handle) 

WORD  handle: 

Clear  the  workstation  specified  by  handle. 

WORD  v-clsva^  (handle) 

WORD  handle: 

Close  the  virtual  workstation  specified  by  the  device  handle  in  parame- 
ter handle. 

WORD  v..clswk  (handle) 

WORD  handle: 

Close  a phj^ical  workstation  with  the  handle  specified  in  parameter 
handle.  This  function  performs  all  necessary  actions  to  complete  out- 
put to  the  device.  For  example,  a printer  device  is  updated,  a metafile  is 
closed,  and  a screen  is  put  into  alpha  mode.  Remember  to  close  all 
open  workstatioi:^  associated  with  the  physical  workstation  before 
closing  the  physical  workstation. 

WORD  v-contoiufill  (handle,  z,  y,  index) 

WORD  handle, 

x.y. 

index: 

Pill  an  area  on  the  display.  Beginning  at  the  starting  point  (z,y),  the 
function  fills  the  area  using  the  current  fill  attributes.  The  fill  pro- 
ceeds to  the  edge  of  the  display  surface,  or  to  a pixel  with  the  color 
index  given  by  index.  If  index  is  negative,  any  color  other  than  color  of 
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the  pixel  at  (x,y)  becomes  a boundaiy  of  the  fill.  This  function  is  not 
required  and  may  not  be  available  on  all  devices. 

WORD  ▼-cudown  (handle) 

WORD  handle; 

Alpha  cursor  down.  Move  the  alpha  cursor  down  one  row  without 
changing  its  horizontal  position.  If  the  cursor  is  at  the  bottom  row. 
nothing  happens. 

WORD  T-coiiiome  (handle) 

WORD  handle; 

Home  alpha  cursor.  Move  the  alpha  ciursor  to  its  home  position,  usu- 
alty  the  upper  left  comer. 

WORD  ▼-curieft  (handle) 

WORD  handle; 

Alpha  cursor  left.  Move  the  alpha  cursor  one  column  to  the  left  with- 
out changing  its  vertical  position.  If  the  cursor  is  at  the  furthest  left 
column,  nothing  happens. 

WORD  v-cuRight  (handle) 

WORD  handle; 

Alpha  cursor  right  Move  the  alpha  cursor  one  column  to  the  right 
without  changing  its  vertical  position.  If  the  cursor  is  at  the  furthest 
right  column,  nothing  happens. 

WORD  v-jcnrtexl:  (handle,  str) 

WORD  handle; 
char  *str; 

Output  cursor  addressable  alpha  text  Hiis  function  writes  the  string 
in  str  starting  at  the  current  alpha  cursor  position.  Ihe  alpha  text 
attributes  current^  in  effect  are  used  for  the  output 

WORD  v_cunq>  (handle) 

WORD  handle; 

Alpha  cursor  up.  Move  the  alpha  cursor  up  one  row  without  changing 
its  horizontal  position.  If  the  cursor  is  at  the  top  row,  nothing 
happens. 
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WORD  y-dspcur  (handle,  z,  y) 
WORD  handle, 
x.r. 


Place  graphic  cursor.  The  graphic  cursor  is  placed  at  the  location  spec- 
ified by  X and  y. 

WORD  v-eeol  (handle) 

WORD  handle; 

Erase  to  end  of  alpha  text  line.  This  function  erases  all  alpha  cells  from 
the  current  alpha  cursor  position  to  the  end  of  the  current  line.  The 
cell  at  the  current  alpha  cursor  position  is  not  changed. 

WORD  y-eeos  (handle) 

WORD  handle: 

Erase  to  end  of  alpha  screen.  This  fimctlon  erases  all  alpha  cells  from 
the  current  alpha  cursor  position  to  the  end  of  the  screen.  The  cell  at 
the  current  alpha  cursor  position  is  not  changed. 

WORD  y.jeilarc  (handle,  z,  y,  zrad,  yrad,  began^  endang) 

WORD  handle, 

*.y. 

zxad,  yrad, 
b^^ng,  endang; 


Draw  an  ellipse.  The  center  of  the  ellipse  is  placed  at  coordinate  (z,y). 
The  X radius  is  given  by  zrad  and  is  measured  along  the  x axis  from  the 
center.  The  y radius  is  measured  along  the  y axis  from  the  center  and 
is  given  by  yrad.  The  arc  starts  at  angle  begang  and  moves  counter- 
clockwise to  endang.  The  angles  measure  tenths  of  degrees  and  range 
from  0 to  3600. 

WORD  y_ellipse  (handle,  z,  y,  zrad,  yrad) 

WORD  handle, 
z,y, 

zrad,  yrad; 

Draw  an  ellipse.  The  center  of  the  ellipse  is  placed  at  coordinate  (z,y). 
The  X radius  is  given  by  zrad  and  is  measured  along  the  x axis  from 
the  center.  The  y radius  is  measured  along  the  y axis  from  the  center 
and  is  given  by  yrad.  Pill  area  attributes  are  us^. 
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WORD  v_dlpie  (handle,  z,  y,  ziad,  yxad,  begang,  endang) 

WORD  handle, 

x.y. 

zrad,  yxad, 
begang,  endang; 

Draw  an  ellipse.  The  center  of  the  ellipse  is  placed  at  coordinate  (z,y). 
The  X radius  is  given  by  zrad  and  is  measured  along  the  x axis  horn 
the  center.  The  y radius  is  measured  along  the  y axis  from  the  center 
and  is  given  by  yxad.  The  arc  starts  at  angle  be^mg  and  moves  coun- 
terclockwise to  endang.  The  angles  measure  tenths  of  degrees  and 
range  from  0 to  3600.  After  the  arc  is  drawn,  each  end  is  connected  to 
the  center  to  complete  the  pie  shape.  Fill  area  attributes  are  used. 


WORD  y_enter_cur  (handle) 
WORD  handle; 


Enter  alpha  mode.  This  function  causes  the  device  to  enter  alpha 
mode  if  alpha  mode  is  different  from  graphics  mode.  Using  this  func- 
tion allows  cursor  address  and  ensures  that  the  device  makes  the 
transition  from  graphics  mode  to  alpha  mode  property. 

WORD  vez-butv  (handle,  pnsrcode,  psavcode) 

WORD  handle, 

*pu8xcode, 

**psavcode; 


Exchange  mouse  button  change  vector.  This  function  allows  the  appli- 
cation to  specify  a routine  to  be  executed  each  time  the  state  of  the 
mouse  button  changes.  The  application  routine  receives  control  after 
the  button  state  is  determined  and  before  the  mouse  button  driver  is 
activated.  The  application  code  address  is  given  by  pusrcode.  The 
previous  address  is  returned  through  psavcode. 

When  the  application  code  is  invoked,  interrupts  are  disabled  and 
should  not  be  enabled.  It  is  the  responsibility  of  the  application  code  to 
save  and  restore  any  registers  it  uses.  The  application  code  Is  started 
using  the  JSR  instruction,  and  the  routine  shovild  exit  using  the  RTS 
instruction. 

When  the  s^pllcation  routine  is  called,  register  DO.w  contains  the 
mouse  button  state.  Each  bit  set  to  1 indicates  the  button  is  pressed. 
Bit  0 corresponds  to  the  furthest  left  button,  bit  1 to  the  next  button 
to  the  right,  and  so  on.  The  application  routine  may  change  DO.w  to 
force  certain  buttons  to  be  down  or  up. 
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WORD  viK-corv  (liandle,  pnarcode,  psavoode) 

WORD  handle, 

*pnsrcode, 

**psavcode; 

Exchange  cursor  change  vector.  This  function  allows  the  application 
to  specify  a routine  to  be  executed  each  time  the  cursor  is  drawn.  The 
application  routine  reives  control  whenever  the  cursor  position 
should  be  updated.  The  application  routine  can  take  over  drawing  the 
cursor  or  can  perform  some  action  and  have  the  VDI  draw  the  cursor. 
The  application  code  address  is  given  by  pusrcode.  Hie  previous 
address  is  returned  through  psavcode. 

When  the  application  code  is  invoked,  interrupts  are  disabled  and 
should  not  be  enabled.  It  is  the  responsibility  of  the  application  code  to 
save  and  restore  any  registers  it  uses.  The  application  code  is  started 
using  the  JSR  instruction,  and  the  routine  should  exit  using  the  RTS 
instruction. 

When  the  application  routine  is  called,  register  DO.w  contadns  the 
new  X coordinate  and  Dl.w  contains  the  new  y coordinate.  The  appli- 
cation routine  may  chamge  DO.w  amd  Dl.w  to  change  the  location  of 
the  cursor  on  the  screen.  If  the  application  routine  does  not  draw  the 
cursor,  it  should  issue  a JSR  instruction  to  the  address  in  psavcode  to 
draw  the  cursor. 

WORD  v-esit-cnr  (handle) 

WORD  liandle; 

Exit  alpha  mode.  This  function  causes  the  device  to  enter  graphics 
mode  if  graphics  mode  is  different  than  alpha  mode.  Using  this  func- 
tion ensures  that  the  device  makes  the  transition  from  alpha  mode  to 
graphics  mode  propeify. 

WORD  vez_motv  (liandle,  pusrcotte,  psavcode) 

WORD  liandle, 

*pasrcode, 

**psavcode; 

Exchange  mouse  movement  vector.  This  function  allows  the  applica- 
tion to  specify  a routine  to  be  executed  each  time  the  mouse  moves  to 
a new  location.  The  application  routine  receives  control  after  the  x and 
y coordinates  are  determined  and  before  the  mouse  driver  is  updated 
or  the  mouse  form  is  redrawn  on  the  screen.  The  application  code 
address  is  given  by  pnsicode.  The  previous  address  is  returned 
through  psavcode. 

When  the  application  code  is  invoked,  interrupts  are  disabled  and 
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should  not  be  enabled.  It  is  the  responsibility  of  the  application  code  to 
save  and  restore  any  registers  it  uses.  The  application  code  is  started 
using  the  JSR  instruction,  and  the  routine  should  exit  using  the  RTS 
instruction. 

When  the  £q>plication  routine  is  called,  register  DO.w  contains  the 
new  X coordinate  and  Dl.w  contains  the  new  y coordinate  The  appli- 
cation routine  may  change  lX).w  and  Dl.w  to  change  the  location  of 
the  mouse  on  the  screen. 

WORD  vez_tiiinr  (handle,  tim_addr,  otim-addr,  tim-conv) 

WORD  handle, 

*tim-addr, 

**otim-addr, 

*tini_conv; 


Exchange  the  timer  interrupt  vector.  This  function  allows  the  applica- 
tion to  execute  a routine  each  time  a timer  tick  occurs.  The  routine  to 
be  executed  is  given  by  tim-addr.  The  previous  timer  interrupt  vector 
address  is  returned  in  otim-addr.  The  number  of  milliseconds  per 
timer  tick  is  returned  in  tim_conv. 

When  the  application  code  is  invoked,  interrupts  are  disabled  and 
should  not  be  enabled.  It  is  the  responsibility  of  the  Explication  code  to 
save  and  restore  any  registers  it  uses.  The  application  code  is  started 
using  the  JSR  instruction,  and  the  routine  should  exit  using  the  RTS 
instruction. 


WORD  T-fillarea  (handle,  count,  p^axray) 

WORD  handle, 
count, 

p^axxay{2  * count]; 

Fill  a complex  pol}^on.  The  number  of  vertices  in  the  polygon  is  given 
by  count,  and  the  coordinate  of  the  vertices  are  in  psyarray.  The  area 
is  outlined  with  a solid  line  if  the  fill  perimeter  visibility  is  on  (see 
vs£-perimeter( ) ).  The  area  is  filled  using  the  attributes  fill  area  color, 
interior  style,  writing  mode,  and  st^e  Index. 

If  the  device  does  not  have  area  fill  capability,  the  VDI  draws  the 
outline  of  the  polygon  using  the  current  fill  area  color.  The  device  drive 
ensures  that  the  fill  area  is  closed  by  connecting  the  last  point  to  the 
first  point 

A polygon  with  zero  Euea  is  displayed  as  a dot  if  the  perimeter  visibil- 
ity is  on;  otherwise  nothing  is  drawn.  A polygon  with  only  one  end- 
point is  ignored. 
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WORD  v_fomLaid7  (handle) 

WORD  handle; 

Form  advance.  The  printer  advances  to  the  next  page.  This  function 
could  be  used  instead  of  the  ▼_clrwk( ) function  so  that  the  current 
printer  display  list  is  retained. 

WORD  v-get-pixel  (handle,  z,  y,  dndez) 

WORD  handle. 

x.y. 

*pel,  *cindes; 

Get  the  pixel  value  and  color  index.  This  function  returns  the  pixel 
value  and  color  index  for  the  pixel  at  location  (z.y).  The  pixd  value  is 
returned  in  pel  and  the  color  index  is  returned  in  dndes. 

Note  that  color  index  0 is  the  background  color.  The  YDI  may  return 
0,  or  may  return  the  index  of  the  current  color  used  for  the  back- 
ground. 

WORD  ▼.gtext  (handle,  z.  y,  str) 

WORD  handle, 

x.y; 

char  *str; 

Write  graphic  text  at  the  coordinates  given  by  z and  y.  The  text  for 
the  string  to  draw  is  pointed  to  by  str.  The  text  alignment  is  set  by 

vst_allgnment( ). 

WORD  v-hardcopy  (handle) 

WORD  handle; 

Hard  copy.  This  function  causes  the  image  on  the  physical  screen  to 
be  copied  to  a printer  or  other  attached  hard  copy  device.  This  func- 
tion is  device-specific  and  may  not  be  available. 

WORD  v-hide-c  (handle) 

WORD  handle; 

Hide  cursor.  This  function  hides  the  current  cursor  form.  Hie  ▼- 
show-c( ) and  v-hide-cf ) functions  are  nested.  The  v-show-cf ) fimc- 
tlon  must  be  called  as  many  times  as  the  v-hide.^ ) function  was 
called  since  the  cursor  disappeared  for  the  cursor  to  become  visible 
again.  For  example,  if  the  cursor  is  visible  and  ▼ Jiide-cf ) is  called  five 
times,  v-ahow-cO  must  be  called  five  times  before  the  cursor  re- 
appears. This  nesting  can  be  overridden  through  the  v-show-cf ) func- 
tion. 
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WORD  ▼-justified  (handle,  x,  y,  str,  len,  word-space,  char_space) 
WORD  handle; 
z.y: 

char  *str; 

WORD  len,  word-qwce,  char-space; 

Output  Justified  text  The  string  to  output  is  pointed  to  by  str.  The 
position  of  output  is  at  coordinate  (x,y).  The  length  in  which  the 
justification  is  to  take  place  is  given  by  len,  measured  in  the  current 
coordinate  ^tem.  If  word-space  is  TRUE,  inter-word  spacing  modifica- 
tion is  used.  If  diar-space  is  TRUE,  inter-character  spacing  modifica- 
tion is  used.  The  function  uses  the  current  text  attributes. 

WORD  v-meta-estents  (handle,  min_x,  min-y,  max-x,  max-y) 
WORD  handle, 

«nfn  min-y, 
max-x,  max-y; 

Update  metafile  extents.  This  function  writes  the  minimum  and  max- 
imum X and  y values  to  the  metafile  header.  These  extents  provide  an 
application  with  a quick  indication  of  the  minimum  rectan^e  that 
will  bound  all  primitives  output  to  the  metafile.  If  this  function  is  not 
used  when  outputting  to  a metafile,  the  extents  will  be  0. 

WORD  vm-filename  (handle,  filename) 

WORD  handle; 

char  *filename; 

Change  the  GEM  VDI  file  name.  The  default  file  name  for  a metafile  is 
GEMF1LE.GEM.  The  new  file  name  to  be  used  is  given  by  string  file- 
name. Only  the  filename  portion  of  the  string  is  used.  The  file  type 
.GEM  is  always  used.  This  function  must  be  called  immediately  after 
opening  the  metafile  with  the  v-opnv^ ) function:  otherwise  &e  file 
name  is  not  changed.  The  function  also  closes  any  open  metafiles. 

WORD  v-opnwriE  (work-in,  handle,  woi^out) 

WORD  work-in[], 

^handle, 

work-ont; 

Open  a virtual  workstation.  The  values  for  arrays  work-in[  ] and  work- 
on^  ] are  the  same  as  for  v-opnwkl ).  The  parameter  handle  has  the 
device  handle  of  the  ph3«lcal  woikstatlon  when  the  function  is  called. 
Upon  return,  handle  contains  the  new  device  handle  for  the  virtual 
workstation.  A returned  device  handle  of  0 indicates  a failure  to  open 
the  virtual  workstation. 
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Note:  Not  all  input  devices  associated  with  the  virtual  workstation 
work. 

WORD  v-opnwk  (woift_in,  handle,  wo^out) 

WORD  work-in(], 

^handle, 

woriL.out(]; 

Open  a physical  workstation  for  use  by  a program.  This  function  uses 
the  parameters  in  array  work_in(  ] to  set  the  initial  workstation  at- 
tributes. The  new  workstation  handle  is  returned  in  parameter  handle, 
and  various  workstation  attributes  are  returned  in  array  woifc-out(  ]. 
The  function  returns  0 as  the  device  handle  if  a workstation  could  not 
be  opened.  The  woric_in(  ] array  is  defined: 


Element 

Description 

0 

Device  id  number  indicating  the  device  driver  to  be  loaded  as 
specified  in  file  ASSIGN.SYS 

1 

Line  type 

2 

Pofy-llne  color  index 

3 

Marker  type 

4 

Poly-marker  color  index 

5 

Text  face 

6 

Text  color  index 

7 

Fill  interior  stjie 

8 

Fill  style  index 

9 

Fill  color  index 

10 

Coordinate  ^tem  selection 

0 = Map  full  NDC  to  full  RC 

1 = Reserved 

2 = Use  RC  system 

The  work-out( ) array  is  defined: 

Element 

Description 

0 Maximum  addressable  width  in  rasters  or  steps  (that  is,  640 

means  addressable  area  is  from  0 through  639) 

1 Addressable  height  in  raster  or  steps 

2 Device  Coordinate  units  flag 

0 = device  is  capable  of  precise  scaling  (usualfy  a plotter  or 
printer) 

1 = device  is  not  capable  of  precise  scaling 

3 Vndth  of  one  pixel  (or  output  unit)  in  microns 

4 Height  of  one  pixel  in  microns 
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Element Description 

5 Number  of  character  heights;  0 means  continuous  scaling 

6 Number  of  line  types 

7 Number  of  line  widths;  0 means  continuous  scaling 

8 Number  of  marker  types 

9 Number  of  marker  sizes;  0 means  continuous  scaling 

10  Number  of  faces  supported  (not  the  highest  face  number  index) 

1 1 Number  of  patterns 

12  Number  of  hatch  st^es 

13  The  number  of  predefined  colors  that  can  be  slmultaneousty 

displayed  on  &e  device 

14  Number  of  generalized  drawing  primitives  (GDPs) 

15-24  These  10  elements  indicate  which  GDPs  are  supported.  Each  GDP 
Is  given  a value  In  the  table  below.  If  fewer  than  10  GDPs  are 
available,  the  value  — 1 is  used  to  fill  the  remaining  elements. 

1 Bar 

2 Arc 

3 Pie  slice 

4 Circle 

5 Ellipse 

6 Elliptical  arc 

7 Elliptical  pie 

8 Rounded  rectangle 

9 Filled,  rounded  rectangle 

10  JustlHed  graphics  text 

25-34  For  each  GDP  listed  above,  the  corresponding  element  In  this  list 
indicates  the  attribute  set  for  that  particular  GDP.  The  attribute 
values  are: 

0 Poly-Une 

1 Poly-marker 

2 Text 

3 Fill  area 

4 None 

35  Color  capability  flag 

0  = No;  1 = Yes 

36  Text  rotation  capability  flag 

0  = No;  1 = Yes 

37  Fill  area  capability  flag 

0 = No;  1 =Yes 

38  Cell  array  operation  capability  flag 

0 = No;  1 = Yes 

39  Number  of  available  colors  (total  number  of  colors  in  the  color 

palette) 

0 = Continuous  (more  than  32,767  colors) 

2 = Monochrome  (black  and  white) 

>2  = Number  of  colors 

40  Number  of  locator  devices 

1 = Kq^xjard  only 

2 = Keyboard  plus  other  devices 

41  Number  of  valuator  devices 

1 = Keyboard  only 

2 = Other  device  available 
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Element  Description 

42  Number  of  choice  (button)  devices 

1 = Keyboard  only 

2 = Other  device  available 

43  Number  of  string  devices  available 

1 = Kqdx>ard 

2 = Other  device  available 

44  Workstation  type 

0 = Output  onty 

1 = Input  onfy 

2 = Input  and  output 

3 = Reserved 

4 = Metafile  ou4>ut 

45  Minimum  character  width  (not  cell  width)  in  ciurent  x coordinates 

46  Minimum  character  character  height  in  current  y coordinates 

47  Maximum  character  width  in  current  x coordinates 

48  Maximum  charcter  height  In  current  y coordinates 

49  Minimum  line  width  In  current  x coordinates 

50  0 

51  Maximum  line  width  In  current  x coordinates 

52  0 

53  Minimum  marker  width  in  current  x coordinates 

54  Minimum  marker  height  in  current  y coordinates 

55  Maximum  marker  width  In  current  x coordinates 

56  Minimum  marker  height  in  current  y coordinates 


WORD  v-output-window  (handle, 

WORD  handle; 

ayarray(4I; 

Ou4>ut  window.  Output  the  rectangular  area  specified  In  xyarray  to 
the  printer.  This  function  is  similar  to  the  v-iq>dwk( ) function  except 
that  the  output  rectangle  must  be  specified. 

WORD  ▼-pieslice  (handle,  z,  y,  red,  begang,  endai^) 

WORD  handle, 
z,y,  tad, 
be^mg,  endang; 


Draw  a circular  pie  slice.  The  center  of  the  circle  is  placed  at  coordi- 
nates (x,y)  and  the  radius,  tad,  is  measiued  along  the  x axis.  The  arc 
starts  at  the  angle  bt^ang  and  proceeds  counterclockwise  to  angle 
endang.  The  parameters  measure  an^es  in  tenths  of  a degree  and  can 
range  from  0 through  3600.  The  arc  is  drawn  and  each  end  is  con- 
nected to  the  center  to  complete  the  slice.  Fill  area  attributes  are  used. 
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WORD  y^line  (handle,  count,  fu^anay) 

WORD  handle, 
count, 

payanay[2  * count]; 

Draw  multiple  line  segments.  The  number  of  points  In  the  p^yanay  Is 
given  by  count  The  function  starts  drawing  from  the  first  point  In  the 
pxyarray  and  continues  to  connect  points  with  line  segments.  The  VDI 
displays  a zero  length  line  as  a point  The  attributes  of  color,  line  type, 
line  width,  end  s^e.  and  current  writing  mode  are  all  used. 

WORD  y..pmariEer  (handle,  count,  p^granay) 

WORD  handle, 
count, 

paqranay(2  *conntj; 

Draw  a set  of  markers  at  the  points  given  In  the  psyanay.  The  number 
of  points  to  draw  Is  given  by  count  The  markers  use  the  attributes 
color,  scale,  type,  and  writing  mode. 

WORD  vq-cellan^  (handle,  fuq^anay,  row Jength,  num_rows, 
el-used,  rows-used,  stat  colarray) 

WORD  handle, 

piQrairayfd], 
zow-lengUi,  nnm_xows, 

*eL.used,  *rows-used, 

*stat, 

colanaytrow-lengtfa  * num-iows); 

Inquire  cell  array.  This  function  returns  the  ceU  array  definition  of  the 
pixels  contained  In  the  rectangle  specified  In  p^aziay.  Color  indices 
are  returned  one  row  at  a time  In  colanay,  starting  from  the  top  of  the 
rectangular  area  and  proceeding  downward.  Parameter  row  Jength  Is 
the  length  of  each  row  In  colarray,  and  num-rows  Is  the  number  of 
rows  In  colamqr* 

The  number  of  elements  used  In  each  row  of  colamgr  Is  returned 
In  el-used,  and  the  number  of  rows  used  In  colanay  Is  returned  In 
rows-used.  If  an  Invalid  value  Is  found,  stat  Is  set  to  1;  otherwise  stat 
returns  as  0. 

WORD  vq_chcell8  (handle,  nunujows,  num_colunins) 

WORD  handle, 

*num-tow8,  *nnm_colunms; 
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Inquire  addressable  alpha  character  cells.  This  function  returns  the 
number  of  vertical  (ntun-ioiwB)  and  horizontal  (nmii-colamiis)  posi- 
tions at  which  the  ^pha  cursor  can  be  positioned.  If  such  addi^ing 
Is  not  possible,  the  v^ue  is  — 1. 

WORD  vq_color  (handle,  color-index,  set-flag,  xgb) 

WORD  handle, 

color-lndeK,  set-flag, 

1^(31: 

Inquire  color  representation.  Hiis  function  returns  the  color  output 
for  color  index  color-index.  The  intensity  for  each  color  is  returned  in 
rgb  where  rgb{0]  is  red,  igb(l]  is  green,  and  ^[2]  is  blue.  The  inten- 
sity ranges  from  0 to  1000.  The  function  can  return  the  set  or  realized 
color  intensities.  The  set  color  intensities  are  the  Intensities  in  the 
lookup  table.  The  realized  color  Intensities  are  the  intensities  used  by 
the  device  (since  a device  may  not  have  1000  levds  of  intensi^).  The 
set  values  are  returned  when  set-flag  is  0.  If  set-flag  is  1,  the  realized 
values  are  returned. 

WORD  vq-cnraddiess  (handle,  row_num,  col  nnm) 

WORD  handle, 

*row-nnm,  *col-nimu 

Inquire  current  alpha  cursor  address.  The  current  row  and  column 
position  of  the  alpha  cursor  is  returned  in  row-nnm  and  col-niim, 
respectively. 

WORD  vq-extnd  (handle,  owflag,  woA-out) 

WORD  handle, 
owflag, 

woriE-out(57]; 

Extended  inquire.  This  function  returns  device-specific  information 
regarding  a workstation.  This  function  has  two  output  options.  When 
owflag  is  0,  the  work-out  array  contains  the  same  values  returned  by 
the  v-opnwk( ) function.  When  owflag  is  1,  the  work-out  array  de- 
ments are  defined; 


Element Description 

0 Screen  type: 

0 = not  screen 

1 = separate  alpha  and  graphic  controllers;  separate  video 
screens 

2 = separate  alpha  and  graphic  controllers;  common  video 
screen 
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Element Description 

3 = common  alpha  and  graphic  controllers;  separate  image 
memory 

4 = common  alpha  and  graphic  controllers;  common  image 
memory 

1 Number  of  background  colors  available 

2 Number  of  text  effects  (see  vst_effects( ) ) 

3 Scaling  of  rasters;  0 = no,  1 = yes 

4 Number  of  planes 

5 Lookup  table:  0 = not  supported,  1 = supported 

6 Number  of  16-by-16  pixd  raster  operations  per  second 

7 Contour  fill  c^abilify 

8 Character  rotation: 

0 = none 

1 = 90  degree  increments  onfy 

2 = arbitrary  angles 

9 Number  of  writing  modes  available 

10  Input  modes  available: 

0 = none 

1 = request  onfy 

2 = sample  and  request 

1 1 Text  ali^unent  capkblllly:  0 = no,  1 = yes 

12  Inking  capability;  0 = no,  1 = yes 

13  Rubberbanding: 

0 = none 

1 = nibberband  lines 

2 = rubberband  lines  and  rectangles 

14  Maximum  number  of  vertices  for  poty-llnes,  poly-markers,  or 

filled  areas,  — 1 if  there  is  no  limit 

15  Maximum  Int^er  Inputs  to  VDI,  or  — 1 if  there  is  no  limit 

16  Number  of  available  mouse  keys 

17  Line  s^e  capability  for  wide  lines:  0 = no,  1 = yes 

18  Writing  modes  for  side  lines 

19-56  Reserved,  all  Os 


WORD  vqfLatttibntes  (handle,  attrib) 

WORD  handle, 
atnib[4]: 

Inquire  current  fill  area  attributes.  The  function  returns  the  current 
attribute  settings  for  fill  area  operations  in  attxlb.  The  dements  of 
attrib  are  defined: 


Element 

Description 

0 

Fill  Interior  style 

1 

Fill  area  color  index 

2 

Fill  area  style  index 

3 

Current  writing  mode 
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See  also  vsfLcolor( ),  vsfUnfexior( ),  vsfLpeiimeterC ),  vsfLstyle( ),  and 
vswr_mode( ). 

WORD  vqln-mode  (handle,  dev-type,  input-mode) 

WORD  handle, 
dev-type, 

*input_mode; 

Inquire  input  mode.  This  function  returns  the  current  input  mode 
(through  input-mode)  for  the  specified  device  type  (dev-type).  Valid 
device  types  are: 

1 = locator 

2 = valuator 

3 = choice 

4 = string 

The  input  mode  value  returned  is  1 for  request  mode  and  2 for  sample 
mode. 

WORD  vq-hey-s  (handle,  pstatus) 

WORD  handle, 

*p8tatus; 

Sample  keyboard  state  information.  The  fimction  returns  the  current 
state  of  the  kQ^board's  Control,  Shift,  and  Alternate  keys.  The  state  of 
each  key  is  returned  as  a bit  setting  in  pstatus.  If  the  bit  is  1,  the  key 
is  down.  The  bits  are  defined: 


Bit 

Key 

0 

Right  shift 

1 

Left  shift 

2 

Control 

3 

Alternate 

WORD  vql-attributes  (handle,  attiib) 

WORD  handle, 
attiib[4]; 

Inquire  current  poly-line  attributes.  The  function  returns  the  current 
attribute  settings  for  poly-line  operations  in  attrib.  The  elements  of 
atttib  are  defined: 
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Element Description 

0 Current  poly-line  line  type 

1 Current  poly-line  color  index 

2 Current  writing  mode 

3 Current  line  width 


See  also  vsl_color( ),  vsl-ends( ),  vsL.t7pe( ),  vsL.width( ),  and  vswr- 
mode( ). 

WORD  vqm^ttiilmtes  (handle,  attrib) 

WORD  handle, 
attrib[4]; 

Inquire  current  poly-marker  attributes.  The  function  returns  the  cur- 
rent attribute  settings  for  poty-marker  operations  in  attrib.  The  ele- 
ments of  attrib  are  defined: 


Element 

Description 

0 

Current  poly-marker  type 

1 

Current  poty-marker  color  index 

2 

Current  writing  mode 

3 

Current  marker  height 

See  also  vsm-color( ),  V8m_height( ),  V8m-iype( ),  and  vwsr_mode( ). 

WORD  vq-monse  (handle,  pstatua,  z,  y) 

WORD  handle, 

*pstatii8, 

*x,  *T» 


Sample  mouse  button  state.  Hie  status  of  the  mouse  button  is  re- 
turned in  bit  settings  of  pstatus.  If  the  bit  Is  1,  the  button  is  down.  Bit 
0 corresponds  to  the  furthest  left  button,  bit  1 to  the  next  button  to 
the  right,  and  so  on.  The  function  also  returns  the  current  coordinates 
of  the  cursor  in  z and  y. 

WORD  vq_tabstatus  (handle) 

WORD  handle; 

Inquire  tablet  status.  This  function  returns  the  availability  status  of  a 
graphics  tablet  mouse,  jo3^tick,  or  similar  device.  If  the  function 
returns  0.  no  tablet  is  available.  If  it  returns  1,  a tablet  is  available. 
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WORD  vqt_attribiites  (handle,  attilb) 

WORD  handle, 
attrlb(0]; 

Inquire  current  graphic  text  attributes.  The  function  returns  the  cur- 
rent attribute  settings  for  graphic  t&ct  operations  in  attxib.  The  ele- 
ments of  attrib  are  defined: 


Element 

Description 

0 

Graphic  text  face 

1 

Graphic  text  color  index 

2 

An^e  of  text  baseline  rotation  (0-3600) 

3 

Horizontal  alignment 

4 

Vertical  alignment 

5 

Writing  mode 

6 

Character  width  in  coordinate  units 

7 

Character  height  in  coordinate  units 

8 

Cell  width  in  coordinate  units 

9 

Cell  height  in  coordinate  units 

See  also  vat-alignmentf ),  vst_color( ),  vst_fiDnt( ),  vst_helght( ),  vst_ 
rotatlonf ),  and  vswr_mode( ). 

WORD  vqt-estent  (handle,  str,  extent) 

WORD  handle, 

extent(8], 
char  *str; 

Inquire  text  extent  Given  the  string  in  str,  the  function  returns  four 
points  describing  a rectangle  that  encloses  the  text  The  first  point 
(eztent(0]  and  estent(l])  corresponds  to  the  lower  left  comer.  The 
second  point  is  the  lower  right  comer.  The  third  point  is  the  upper 
right  comer.  The  fourth  point  is  the  upper  left  comer.  All  text  attri- 
butes, including  effects  and  baseline  rotation,  affect  the  calculation. 

WORD  vqt-fontlnfi>  (handle,  minADE,  mazADE, 
distances,  mazwldtti,  &) 

WORD  handle, 

*minAnic,  *ma2cADE, 
distances!  5], 

*mazwidlh, 

&(3|: 
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Inquire  current  face  information.  This  function  obtains  size  informa- 
tion regarding  the  current  ^q)e  face,  taking  into  account  the  current 
height  and  effects.  The  ASCII  Decimal  Equivalent  of  the  first  and  last 
characters  in  the  font  are  returned  in  minADE  and  mazADE,  respec- 
tively. The  maximum  cell  width,  not  including  effects,  is  returned 
through  maxwidth.  The  distances  array  is  defined: 


Element 

Description 

0 

Bottom  line  distance  relative  to  basdine 

1 

Descent  line  distance  relative  to  baseline 

2 

Half  line  distance  relative  to  baseline 

3 

Ascent  line  distance  relative  to  baseline 

4 

Top  line  distance  relative  to  baseline 

The  fit  array  is  defined; 

Element 

Description 

0 

Increase  in  character  width  due  to  effects 

1 

Left  offset 

2 

Ri^t  offset 

WORD  vqt-name  (handle,  element-nnm,  face-name) 

WORD  handle. 

element-nnm; 
char  f3ce-name{32]; 

Inquire  face  name  and  index.  The  function  obtains  the  description 
data  regarding  face  element  element-num.  The  string  face-name  is 
set  by  the  function  and  consists  of  two  parts.  The  first  16  characters 
are  the  face  name  (e.g.,  Swiss  721  or  Dutch  801).  and  the  next  16 
characters  sire  the  face  style  (e.g..  Bold.  Italic,  Roman,  etc.).  The  func- 
tion returns  the  ID  number  of  the  current  type  face. 

WORD  vqt-width  (handle,  diar,  ceU-widlh,  left-delta,  right-delta) 
WORD  handle, 
diar, 

*ceU-widtli.  *left-delta,  *right_delta; 

Inquire  character  cell  width.  This  function  returns  the  character  cell 
values  for  a particular  character.  The  ASCII  character  code  Is  given  by 
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char.  The  cell  width  and  left  and  right  delta  alignment  are  returned  in 
celL-widht,  lefit-delta,  and  right-delta,  respective^  (see  Figure  A-1). 
Tlie  function  returns  the  value  of  char,  or  — 1 if  an  invalid  value 
was  used. 

WORD  v-rboz  (handle,  piqrairay) 

WORD  handle, 

P^arrayldl; 

Draw  a rectangle  with  rounded  comers.  The  rectangle  is  given  by  the 
points  in  payanay. 

WORD  v-xflxNC  (handle,  p^array) 

WORD  handle. 


Character 


Figure  A-1  Character  Cell 
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Draw  a filled  rectangle  with  rounded  comers.  The  rectan^e  is  speci- 
fied by  the  points  in  pEyanay,  M fill  area  attributes  are  used. 

WORD  ▼-rmcnr  (handle) 

WORD  handle; 

Remove  last  graphic  cursor.  This  function  removes  the  last  graphic 
cursor  placed  on  the  screen. 

WORD  vro-cpylin  (handle,  WT_mode.  poyanay,  psrcBflFDB, 
pdesBODB) 

WORD  handle. 

wr_mode, 

pi^aitay[81; 

FDB  *psrcHSFDB.  *pdesMFDB: 

Perform  opaque  copy  raster  operation.  This  function  copies  a rectan- 
gular raster  from  a source  form  to  a destination  form  using  the  writ- 
ing mode  specified.  The  writing  mode  is  given  by  wr-mode  and  maybe 
one  of  the  following  values; 


Con^nt Value Operation 


ALL_WHITE 

S-AND-D 

S-ANDJNOTO 

S-ONLY 

NOTS-AND-D 

D-ONLY 

S-XOR_D 

S-ORJD 

NOT_SORD 

NOT_SXORD 

NOT_D 

S_OR_NOTD 

NOT_S 

NOTS_ORJD 

NOT_SANDD 

ALL_BLACK 


0 R = 

1 R = 

2 R = 

3 R = 

4 R = 

5 R = 

6 R = 

7 R = 

8 R = 

9 R = 

10  R = 

11  R = 

12  R = 

13  R = 

14  R = 

15  R = 


0 

SANDD 
SAND  (NOT D) 
S 

(NOT  S)  AND  D 
D 

SXORD 
SORD 
NOT(SORD) 
NOT  (SXORD) 
NOTD 

SOR(NOTD) 

NOTS 

(NOTS)ORD 
NOT  (SANDD) 
1 


where  S is  the  source  pixel  value.  D is  the  destination  pixel  value,  and 
R is  the  destination  pixel  value  after  the  operatioa  (NOTE:  Constant 
names  for  modes  10.  11.  and  12  may  n^  to  be  corrected  in  file 
OBDEFSJl.) 

The  px^axTiQr  gives  the  rectangle  in  the  source  form  to  copy  from  in 
elements  0 through  3.  and  the  rectan^e  in  the  destination  to  copy  to 
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in  elements  4 through  7.  If  the  source  and  destination  rasters  are  the 
same,  and  the  source  and  destination  rectangles  overlap,  the  VDI 
ensures  that  the  source  area  is  copied  before  it  is  changed  (that  is, 
when  it  becomes  the  destination  area).  The  fimctlon  performs  the 
copy  operation  pixel  for  pixel. 

If  the  source  and  destination  rectangles  are  not  the  same  size,  the 
VDI  uses  the  destination  as  a pointer  and  uses  the  source  for  the  size. 

The  raster  is  defined  by  the  FDB  structures  pointed  to  by  psrcBlFDB 
and  pdedOPDB.  The  FDB  structure  is  defined  in  GEMDEFS.H  as; 


/*  raster  bit  map  */ 

/*  widtli  of  raster  in  pixels  */ 

/*  height  of  raster  in  pixels  */ 

/*  width  of  raster  in  words  */ 

I*  0=standard,  l=device  format  */ 
/*  number  of  planes  */ 

/*  reserved  */ 


Refer  to  Chapter  7 for  further  details  r^arding  bit  maps  and  rasters. 
Note  that  the  source  and  destination  rasters  must  be  in  the  same  for- 
mat specified  in  fo-stand. 

WORD  vrq-choice  (handle,  ch-in,  ch-out) 

WORD  handle. 

eh  in, 

*ch-out; 

Input  choice,  request  mode.  This  function  waits  imtil  input  from  the 
choice  device  is  available.  The  choice  key  index  is  returned  through 
ch_out  as  a number  from  1 to  a device-dependent  value.  If  the  key 
pressed  is  not  a valid  choice  key,  the  value  in  ch-in  is  returned  as  the 
selection. 

This  function  is  not  required  and  may  not  be  available  on  all 
devices. 

WORD  vrq-locator  (handle,  x,  y,  xout,  yout,  term) 

WORD  handle, 

*.y. 

*xont,  *yout,  *term; 

Input  locator,  request  mode.  This  function  returns  the  position  of  the 
locator  device.  When  the  function  is  called,  it  places  a cursor  at  the 


typedef  struct  fdbstr  { 
WORD  *fd-addr, 
fd-w, 
fd-h, 

fo-wdwidth, 

fd-stand, 

fd-nplanes, 

fd_rl, 

fd-r2, 

fo-t3: 

}FDB: 
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Initial  coordinates  given  by  x and  y.  The  function  then  tracks  the  cur- 
sor based  on  the  input  from  the  locator.  When  a terminating  event 
such  as  pressing  the  mouse  button  or  a key,  occurs,  the  cursor  is 
removed  and  the  function  returns.  The  terminating  event  is  indicated 
in  the  value  of  term  and  the  cursor  coordinates  are  returned  through 
xout  and  yout 

If  both  the  kqdioard  and  another  locator  device  are  available,  the 
cursor  is  tracked  by  input  from  either.  To  determine  the  type  of  termi- 
nating event  the  parameter  term  is  divided  into  its  two  b)des.  The  low 
byte  contains  the  ASCII  value  of  the  character  entered,  if  a kq^press 
was  the  terminating  event  Otherwise,  the  high  byte  contains  a value, 
offset  by  0x20,  indicating  the  locator  button  that  was  pressed.  For 
example,  on  the  mouse,  the  left  button  has  the  value  0x20,  the  next 
button  to  the  right  is  0x21,  etc. 

WORD  vxq-string  (handle,  nuuc-lengUi,  echo-mode,  echo-j^,  str) 
WORD  handle, 

max-length, 

echo-mode,  echo-X7(2]; 
char  str[max-lengUi  1]; 

Input  string,  request  mode.  This  function  accepts  characters  from  the 
string  input  device  until  max-length  characters  have  been  entered  or 
a carriage  return  is  encountered.  If  echo-mode  is  TRUE,  the  charac- 
ters are  echoed  to  the  screen  at  the  coordinates  in  echo-xy  using  the 
current  text  attributes.  Otherwise,  echoing  to  the  screen  is  disabled 
(echoing  of  input  is  not  required  and  may  not  be  available  on  all 
devices).  The  characters  are  returned  in  str  as  a null-terminated 
string. 

If  max-lengdi  is  a negative  value,  the  absolute  value  is  used  as 
above,  and  the  character  codes  will  be  the  standard  keyboard  defined 
in  ^pendix  C.  Otherwise,  the  keycodes  may  be  device-dependent 

WORD  vrq-valtiator  (handle,  vaLJn,  val-ont,  term) 

WORD  handle, 
vaUin, 

*val_out 

*term; 


Input  valuator,  request  mode.  This  function  sets  the  initial  value  of 
the  valuator  to  val-in.  The  final  value  is  returned  throu^  val-ont  The 
terminating  event  is  returned  in  term  (see  vrq_locator( ) for  a descrip- 
tion of  term). 

In  general,  the  valuator  is  the  up  and  down  arrow  keys  on  the  key 
board.  Pressing  the  up  arrow  increases  the  value  by  ten;  pressing  the 
down  arrow  decreases  the  value  by  ten.  Pressing  these  keys  with  the 
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shift  kqr  Increments  or  decrements  the  value  by  one.  The  range  of  the 
valuator  is  from  1 through  100. 

This  ftmctlon  is  not  required  and  may  not  be  available  on  all 
devices. 

WORD  vr_recffl  (handle,  pay  array) 

WORD  handle. 

psyarray[4]; 

Draw  a filled  rectangular  area.  The  rectan^e  is  given  by  array  pj^ar- 
ray.  The  current  fill  area  attributes  are  used,  ^cept  the  perimeter 
which  is  not  drawn. 

WORD  VTt_q>y£m  (handle,  wr-mode.  piyarn^. 

psrcBIFDB.  pdesMFDB.  color-index) 

WORD  handle. 

WT-mode. 

psyarraytS): 

FDB  *psrcMFDB.  *pdesMFDB; 

WORD  color-index[2]; 

Transparent  copy  raster  operation.  This  function  takes  a monochrome 
raster  and  copies  it  to  a color  raster  using  the  writing  mode  specified 
by  wr-mode.  The  same  writing  mode  constant  names  are  used  for  this 
function  as  for  function  v8wr-mode( ).  The  effect  of  each  mode  is 
sUghtty  different 

In  Replace  mode,  the  destination  pixels  are  replaced.  The  for^round 
color  index  is  specified  in  color-indes[0]  and  is  output  for  any  source 
pixel  with  a value  of  1.  The  backgroimd  color  is  specified  in  color- 
index[l]  and  is  output  for  euiy  source  pixel  with  a v^ue  of  0. 

In  Transparent  mode,  the  for^round  color  in  color-index[0]  is  out- 
put for  source  pixels  with  the  value  of  1.  Source  pixels  with  the  value  0 
have  no  effect  and  cOlor-index[l]  is  not  used. 

In  XOR  mode,  the  monochrome  raster  pixels  are  logically  XORed 
with  each  plane  of  the  destination  raster.  The  values  in  coior-indmr 
are  not  used. 

In  Reverse  Transparent  mode,  source  pixels  with  the  value  0 cause 
the  background  color  in  color-indes(l]  to  be  output  to  the  destina- 
tion. Source  pixels  with  the  value  1 have  no  effect  and  color-indes[0] 
is  not  used. 

The  parameters  p^array.  psrCMFDB.  and  pdesMH>B  are  used  in 
the  same  manner  as  in  function  vro_cpyfin( ). 

WORD  VT-tnifin  (handle.  psrcMFDB.  pdesBODB) 

WORD  handle; 

FDB  *pscrSIFDB.  ^pdesBlFDB; 


C Function  Reference  Guide  451 


Transform  the  format  of  a raster.  This  function  converts  a raster  from 
standard  format  to  device-specific  format  or  vice  versa.  The  raster  to 
transform  is  defined  by  the  FDB  structure  pointed  to  by  psrcBIFDB. 
The  result  of  the  transformation  is  placed  in  pdesBlFDB. 

The  type  of  transformation  performed  is  based  on  the  current  value 
of  the  fd-stand  field  of  the  FDB  structure.  If  the  raster  is  in  standard 
format  it  is  converted  to  device-specific  format  If  the  raster  is  in 
device-specific  format  it  is  converted  to  standard  format  In  either 
case,  the  fd-stand  field  of  pde^dFDB  is  set  to  the  resulting  format  It 
Is  the  user’s  responsibility  to  set  all  other  fields  of  the  source  and  des- 
tination FDBs. 

See  Chapter  7 for  further  discussion  about  raster  and  formats.  Refer 
to  function  vxo_ci^fin( ) for  the  definition  of  the  FDB  structure. 

WORD  v-rvoff  (handle) 

WORD  handle; 

Reverse  video  off.  All  subsequent  alpha  text  output  is  done  in  normal 
video. 

WORD  v-ivon  (handle) 

WORD  handle; 

Reverse  video  on.  All  subsequent  alpha  text  output  is  done  in  reverse 
video. 

WORD  vsc-form  (handle,  pcar_foim) 

WORD  handle. 

pcur-l6tm(37]; 

Redefine  cursor.  The  cursor  is  displayed  when  the  vrq-locator( ) or 
v_show_c( ) function  is  called.  The  array  pcnr-form  has  the  following 
structure: 


Element 

Description 

0 

X coordinate  of  hot  spot 

1 

y coordinate  of  hot  spot 

2 

Reserved;  must  be  1 

3 

Mask  color  index  (usually  0) 

4 

Data  color  index  (usually  1) 

5-20 

16-by-16  bit  cursor  mask 

21-36 

16-by-16  bit  cursor  data 

The  hot  spot  is  the  location  of  the  pixel  (relative  to  the  upper  left 
comer  of  the  mouse  form)  used  as  the  current  mouse  position. 
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The  mouse  form  Is  drawn  using  the  following  procedure: 

1.  The  data  under  the  mouse  form  is  saved  so  that  it  can  be  re- 
stored when  the  cursor  moves. 

2.  Bits  set  to  1 in  the  mask  cause  the  corresponding  pixels  to  be  set 
to  the  color  index  in  pcurJTormlS]. 

3.  Bits  set  to  1 in  the  data  cause  the  corresponding  pixels  to  be  set 
to  the  color  index  in  pcaT-form[4]. 

WORD  vs_clip  (handle,  dip  JOag,  pigran^) 

WORD  handle. 

d4>-llag. 

Set  the  dipping  rectangle  for  workstation  handle.  If  clip-flag  is  FALSE, 
clipping  the  VDI  is  tiuned  off.  If  clip-flag  is  TRUE,  clipping  is 
turned  on  and  the  clipping  rectangle  Is  set  to  the  rectangle  in  pqranay 
given  in  the  current  coordinate  system.  The  default  when  a worksta- 
tion is  opened  is  for  dipping  to  be  disabled. 

WORD  vs-color  (handle,  dndes,  ^gb-Jn) 

WORD  handle, 
cindesit 
igb-in[3]; 

Set  the  color  in  the  color  lookup  table.  The  color  index  range  is  device- 
dependent  On  the  Atari  ST,  the  indices  range  from  0 to  15.  The  color 
index  is  given  by  cdndez.  The  color  is  specified  by  mixing  various 
intensities  of  red  (igb-in(0] ),  green  (igb-in[l] ),  and  blue  (zgb-in(2] ). 
The  intensity  can  range  from  0,  meaning  no  color,  to  1000  for  the 
highest  intensity. 

If  no  color  lookup  table  exists,  this  function  performs  no  operation. 
On  a monochrome  device,  the  VDI  maps  any  percentage  of  color  to 
white. 

WORD  vs-cuxaddxess  (handle,  row-num,  col-niun) 

WORD  handle. 

row-num,  coLmum; 

Direct  alpha  cursor  address.  This  function  moves  the  alpha  cursor  to 
the  alpha  cell  specified  by  coordinates  tow-nnm  and  col-num.  Row 
and  column  ntunbers  start  at  1.  Addresses  beyond  the  dlsplayable 
range  of  the  screen  are  set  to  the  nearest  value  within  the  dlsplayable 
area. 
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WORD  vsLjColor  (handle,  color  Jndex) 

WORD  handle. 

color Jndez; 

Set  the  color  Index  for  subsequent  fill  poison  operations.  The  color 
index  specified  by  color-index  refers  to  an  index  in  the  color  lookup 
table  of  the  VDL  At  least  two  colors.  0 and  1,  are  supported.  The  total 
number  of  colors  available  is  device-dependent  If  a color  index  is  out 
of  range,  the  VDI  defaults  to  index  1.  The  function  returns  the  selected 
color  index. 

WORD  iwif  interior  (handle,  fe^e) 

WORD  handle, 
fiiQde; 

Set  the  fill  Interior  style  used  in  subsequent  potygon  fill  operations. 
The  fill  style  is  specified  Ity  fiityde.  Valid  s^e  indices  are: 

0 = hollow 

1 = solid 

2 = pattern 

3 = hatch 

4 = user-defined 

If  an  unavailable  style  index  is  selected,  the  VDI  defaults  to  hollow  fUL 
A hollow  st^e  fills  the  interior  with  the  current  background  color 
(index  0).  Solid  stjde  fills  the  area  with  the  current  flU  color.  Pattern 
and  hatch  st^es  require  a further  selection  through  vafLstylef ).  The 
user-defined  styde  is  set  tty  v8L.udpat( ). 

The  function  returns  the  selected  interior-fill  si^e. 

WORD  vsC-perimeter  (handle,  per-via) 

WORD  handle, 
per_vls; 

Set  the  fill  perimeter  visibility.  When  per.via  is  FALSE,  the  perimeter 
visibility  is  set  to  off.  When  per_vis  is  TRUE,  it  is  set  to  on.  Certain 
polygon  drawing  operations  use  the  perimeter  visibility  setting.  If  the 
setting  Is  on.  a solid  perimeter  is  drawn;  otherwise  no  perimeter  is 
drawn.  The  function  returns  the  current  perimeter  visibility  setting. 

WORD  vsfLstjde  (handle,  fetydc-  Index) 

WORD  handle, 

fistyle-indez; 
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Set  the  fill  s^e  for  interior-fill  stjdes  of  pattern  or  hatch.  If  other 
interior-fill  stjies  are  selected,  this  function  has  no  effect  on  them.  The 
stjde  index  is  specified  in  fittyle-indmc.  Valid  indices  are  shown  in 
Figure  A-2  and  A-3.  The  total  niunber  of  patterns  and  hatches  is 
device-dependent  However,  those  shown  in  the  figures  are  always 
supported.  If  a requested  index  is  not  available,  the  VDI  defaults  to 
index  1.  The  function  returns  the  index  selected. 

WORD  vsfLut^t  (handle,  pfiU-pat,  nplanes) 

WORD  handle, 

pfUL.I>at{16  * nplanes], 
nplanes; 

Set  the  user-defined  fill  pattern.  A pattern  consists  of  a 16-by-16  bit 
array  where  bits  set  to  1 indicate  the  pixel  is  on.  Bit  15  of  the  first 
WORD  is  the  first  pixel  in  the  pattern.  The  bit  array  is  pointed  to  by 

pfill_pat. 

The  number  of  planes  for  multiple-plane  patterns  is  specified  by 
nplanes.  Plane  1 of  the  pattern  is  hdd  in  pfiU-pat  elements  0 through 
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Figure  A-2  Fill  Patterns 
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15:  plane  2 of  the  pattern  is  in  dements  16  through  31:  etc.  Note  that 
the  writing  mode  must  be  Replace  when  using  multiple-plane  pat- 
terns. 

WORD  v-di0W.c  thandle,  reset) 

WORD  handle, 
reset; 

Show  ctusor.  This  function  displays  the  current  cursor  form.  The 
v_diofw.c( ) and  v_hide_c( ) functions  are  nested.  The  v-show-cf ) 
function  must  be  called  as  many  times  as  the  v-hide-c( ) function  was 
called  since  the  cursor  disappeared  for  the  cursor  to  become  visible 
again.  For  example,  if  the  cursor  is  visible  and  v-hide-c( ) is  called  five 
times,  v-diow-c()  must  be  called  five  times  before  the  cursor  re- 
appears. This  nesting  can  be  overridden  by  setting  parameter  reset  to 
0.  When  parameter  reset  is  0,  the  number  of  ▼-hlde-c( ) calls  is  ignored 
and  the  cursor  is  made  visible.  If  reset  is  nonzero,  v-show-c( ) retains 
its  normal  functionality. 

WORD  vsin-inode  (handle,  dev-type,  In-mode) 

WORD  handle. 

dev_type, 

ln_mode; 

Set  the  input  mode  for  logical  input  devices.  The  input  device  to  set  is 
given  by  dev_type.  Valid  logical  devices  are: 

1 = locator 

2 = valuator 

3 = choice 

4 = string 

The  input  mode  to  use  is  set  by  in-mode  where  1 is  request  mode  and 
2 is  sample  mode. 

WORD  vsl-color  (handle,  color-index) 

WORD  handle, 

color.,  index; 

Set  the  color  index  for  subsequent  poly-line  operatlona  The  color 
index  specified  color-index  refers  to  an  index  in  the  color  lookup 
table  of  the  VDI.  At  least  two  colors,  0 and  1,  are  supported.  The  total 
number  of  colors  available  is  device-dependent  If  a color  index  is  out 
of  range,  the  VDI  defaults  to  index  1.  The  function  returns  the  selected 
color  index. 
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WORD  vSL.ends  (handle,  be£_8t3de,  end-atj^e) 

WORD  handle, 

beg-style, 

end-s^e; 

Select  the  line  end  s^e  for  subsequent  poly-Une  operations.  The  start 
of  the  line  has  style  beg-style  and  the  end  of  the  line  heis  style 
end-style.  The  style  may  be  any  one  of  the  following: 

0 = squared  (default) 

1 = arrow 

2 = rounded 

The  squared  and  arrow  ends  stop  at  the  endpoint  of  the  line.  The 
rounded  end  is  drawn  so  that  the  center  of  the  rounding  is  at  the 
endpoint  of  the  line. 

WORD  vsL.type  (handle,  latyle) 

WORD  handle, 
lat^e; 

Set  the  line  type  for  subsequent  poly-line  operations.  The  line  style  is 
set  by  the  index  given  in  Istyde.  The  function  returns  the  line  st^e 
selected.  Tlie  total  number  of  line  styles  is  device-dependent  All  devices 
support  at  leetst  six  lines  stydes  and  one  user-defined  line  style  (see 
Figure  A-4). 


Style  16  bits 

Bit  15  Bit  0 

1 solid  1111111111111111 

2  long  dash  1111111111110000 

3 dot  1110000011100000 

4 dash,  dot  1111111000111000 

5 dash  1111111100000000 

6 dash,  dot,  dot  1111000110011000 

7  user-defined  1111000000001111 


8-n  Device  dependent  line  styles 

Figure  A-4  Line  Styles 


C Function  Reference  Guide  457 


The  lines  are  defined  by  16  bits,  where  1 means  the  pixel  is  on  and  0 
means  the  pixel  is  off.  If  a nondefault  line  width  is  used,  the  device 
may  not  thicken  the  line  styles  and  use  only  a thickened  solid  line. 

WORD  v8L.adsty  (handle,  Ipattem) 

WORD  handle, 

Ipattem; 

Set  the  user-defined  line  style.  When  line  style  index  7 is  in  use,  the 
line  style  provided  in  is  used.  The  pattern  consists  of  16  bits 

where  the  most  significant  bit  is  the  first  pixel  in  the  line. 

WORD  vsl-wldth  (handle,  hvidth) 

WORD  handle, 

Iwidtii; 

Set  the  line  width  for  subsequent  poly-line  operationa  Line  widths  are 
always  odd  numbers.  The  line  width  requested  is  given  by  Iwidth.  If  a 
line  width  selected  is  not  available,  the  closest  line  width  not  greater 
than  the  one  requested  is  chosen.  This  function  is  not  required  and 
may  not  be  available  on  all  devices.  The  function  returns  the  line 
width  selected. 

WORD  vsm-cholce  (handle,  ch-out) 

WORD  handle. 


Input  choice,  sample  mode.  This  function  samples  the  choice  input  If 
input  is  available,  the  function  returns  1 and  the  choice  selection  is 
returned  through  ch_out  If  no  input  is  available,  or  if  an  invalid  key 
was  pressed,  the  function  returns  0.  The  choice  numbers  range  from  1 
to  a device-dependent  value. 

This  function  is  not  required  and  may  not  be  available  on  all  devices. 

WORD  vsm-color  (handle,  color-index) 

WORD  handle, 

color-index; 

Set  the  color  index  for  subsequent  poly-marker  operations.  The  color 
index  specified  by  color-index  refers  to  an  index  in  the  color  lookup 
table  of  the  VDI.  At  least  two  colors,  0 and  1,  are  supported.  The  total 
number  of  colors  available  is  device-dependent  If  a color  index  is  out 
of  range,  the  VDI  defiiults  to  index  1.  The  function  returns  the  selected 
color  index. 
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WORD  vsm-heiglit  (handle,  mheight) 

WORD  handle, 

mheight; 

Set  the  height  of  the  markers  used  in  subsequent  poly-marker  opera- 
tions. The  height  is  given  mheight.  If  the  height  for  the  current 
marker  does  not  exist,  the  VDI  uses  the  closest  height  not  larger  than 
the  height  requested.  The  function  returns  the  actual  height  selected. 

WORD  vamulocator  (handle,  x,  y,  xout,  yout,  tenn) 

WORD  hradle, 

X.  y. 

*xout,  *yout,  *tNm; 

Input  locator,  sample  mode.  This  function  samples  the  input  from  the 
locator  device.  No  cursor  is  automatically  displayed  when  this  function 
is  called  (use  the  v_show_c( ) function).  The  locator  starts  at  the  posi- 
tion specified  1^  x and  y.  The  new  coordinates  of  the  locator  are 
returned  by  xout  and  youL  The  terminating  event,  if  any,  is  returned 
through  term  (see  vrq-locator( ) for  a description  of  term).  Input  is 
taken  from  both  the  keyboard  and  another  locator  device  if  they  are 
available 

Hie  function  returns  a value  of  bit  0 %t  to  1 if  the  locator  coordi- 
nates have  changed  and  bit  1 set  to  1 if  a terminating  event  had 
occurred. 

WORD  vsm-stiing  (handle,  nuuulength,  echo^mode,  echo-igr,  str) 
WORD  handle, 

tTiQV 

echo-mo^,  e<dio-27(2]; 
char  Btr(max-length  -I- 1]; 

Input  string,  sample  mode.  This  function  samples  the  character  input 
and  accepts  characters  until  one  of  the  following  events  occurs: 


data  is  no  longer  available, 
a carriage  return  is  encountered,  or 
max-length  characters  have  been  read. 

If  echo-mode  is  TRUE,  the  characters  are  echoed  to  the  screen  at 
the  coordinates  in  echo-37  using  the  current  text  attributes.  Other- 
wise. echoing  to  the  screen  is  disabled  (echoing  of  input  is  not 
required  and  may  not  be  available  on  all  devices).  The  characters  are 
returned  in  str  as  a null-terminated  string. 
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If  max-length  is  a negative  value,  the  absolute  value  is  used  as 
above,  and  the  character  codes  are  the  standard  keyboard  as  defined 
in  ,^pendix  C.  Otherwise,  the  kq^odes  may  be  device-dependent 
The  function  returns  a 0 if  no  characters  were  available,  or  a posi- 
tive value  if  characters  were  available. 

WORD  vsm-type  (handle,  msymbol) 

WORD  handle, 
msynd>ol{ 


Select  the  marker  type  for  subsequent  poly-marker  operations.  The 
marker  selected  is  given  by  msymboL  The  marker  index  ranges  from  1 
to  a device-dependent  value.  At  leaist  six  markers  are  always  dehned 
the  VDI  (see  Figure  A-5).  If  a marker  index  is  out  of  range,  the  VDI 
defaults  to  the  asterisk  (index  3).  The  function  returns  the  index  of 
the  marker  selected. 

WORD  vBm-valuatoT  (handle,  vaLJn,  vaL_out.  term,  status) 

WORD  handle, 
vaLJn, 

*val_out, 

*term,  *8tatus; 

Input  valuator,  sample  mode.  This  function  tests  for  any  changes  to 
the  valuator.  If  changes  have  been  made,  the  value  of  the  valuator  is 
altered  accordingly.  The  initial  valuator  value  is  given  by  val-in.  The 
resulting  value  is  returned  through  vaL-out.  The  terminating  event,  if 
any,  is  returned  through  term  (see  vrq-locator).  The  status  parameter 
returns  0 if  nothing  happened,  1 if  the  valuator  has  changed,  and  2 if 
a terminating  event  occurred. 

This  function  is  not  required  and  may  not  be  available  on  etll 
devices. 


1 

. 

Dot 

2 

+ 

Plus 

3 

Asterisk 

4 

□ 

Square 

5 

X 

Diagonal  cross 

6 

O 

Diamond 

7 and  up  are  device  dependent 

Figure  A-5  Poly-marittr  Types 
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WORD  vst  alignment  (handle,  hor-in,  vertJn,  hor^ut,  vert-out) 
WORD  handle. 

hor-in,  vert-in, 

*hor-oot,  vert-out; 

Set  the  graphics  text  alignment  for  subsequent  graphics  text  opera- 
tions. Graphics  text  alignment  is  referenced  on  the  (x,y)  point  selected 
in  the  ou^ut  functions  v-gtext( ) and  v-justified( ).  Horizontal  align- 
ment has  three  options: 

0 = left  Justified  where  the  string  starts  at  (xy) 

1 = center  justified  where  the  length  of  the  string  is  centered  about  (xy) 

2 = right  Justified  where  the  string  ends  at  (xy);  left  Justification  is  the 

default  value. 

Vertical  alignment  has  6 options: 

0 = baseline  (default) 

1 = half  line 

2 = ascent  line 

3 = bottom  line 

4 = descent  line 

5 = top  line 

For  vertical  alignment,  the  line  chosen  passes  through  the  point  (xy) 
(see  Figure  A-6  for  line  placement). 

Horizontal  and  vertical  alignment  are  selected  separate^  by  setting 
hor-in  and  vert-in,  respective!/.  The  actual  alignment  values  being 
used  by  the  VDI  are  returned  through  hor-out  and  vert-out.  If  an 
invalid  alignment  value  is  requested,  the  VDI  chooses  the  default 
value. 

WORD  vBt-color  (handle,  color-index) 

WORD  handle. 

color-index; 

Set  the  color  index  for  subsequent  graphic  text  operations.  The  color 
index  specified  by  color-index  refers  to  an  index  in  the  color  lookup 
table  of  the  VDI.  At  least  two  colors.  0 and  1.  are  supported.  The  total 
niunber  of  colors  available  is  device-dependent  If  a color  index  is  out 
of  range,  the  VDI  defaults  to  index  1.  The  function  returns  the  selected 
color  index. 

WORD  v8t-efifectB  (handle,  teffect) 

WORD  handle, 
teffiect; 
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Figure  A-6  Character  Cell 


Set  the  text  ^>ecial  effects  for  subsequent  graphic  text  operations.  The 
bit  settings  of  tefifect  determine  which  effects  are  active.  The  bit  des- 
criptions are: 


Bit 

Description 

0 

Thicken 

1 

Light  intensity 

2 

Skew  (Uke  italic) 

3 

Underline 

4 

Outline 

5 

Shadow 

When  the  bit  Is  set,  the  text  output  has  that  attribute.  Any  combina- 
tion of  text  effects  Is  allowed. 
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The  function  returns  the  effect  setting  selected. 

WORD  V8t_font  (handle,  tfont) 

WORD  handle; 
tibnt; 

Select  the  graphic  character  face  for  subsequent  graphic  text  opera- 
tions. The  face  index  to  use  is  specified  by  tfont.  Some  face  names  and 
indices  are; 


Index 

Name 

1 

^«tem  face 

2 

Swiss  721 

3 

Swiss  721  Thin 

4 

Swiss  721  Thin  Italic 

5 

Swiss  721  Ught 

6 

Swiss  721  Light  Italic 

7 

Swiss  721  It^c 

8 

Swiss  721  Bold 

9 

Swiss  721  Bold  Italic 

10 

Swiss  721  Heavy 

11 

Swiss  721  Heavy  Italic 

12 

Swiss  721  Black 

13 

Swiss  721  Black  Italic 

14 

Dutch  801  Roman 

15 

E)utch  801  Italic 

16 

Dutch  801  Bold 

17 

Dutch  801  Bold  Italic 

Onty  face  1 is  built  into  the  VDI.  All  other  faces  must  be  loaded  from 
face  files  using  the  vst_load_£Dnts( ) function. 

The  function  returns  the  index  of  the  font  selected. 

WORD  yst-height  (handle,  theight,  char-width,  char-height, 
cell-width,  cell  height) 

WORD  handle, 
theight, 

*char-width,  *char-height, 

*cell-width,  *cdl-height; 

Set  the  current  text  height  in  coordinate  units.  The  height  specified 
in  tiieight  is  the  distance  from  the  character  baseline  to  the  top  of  the 
character  cell  (see  Figure  A-7). 

The  function  sets  char-width  and  Char-height  to  the  character 
width  and  height  respectlvdy.  The  ceD  width  and  cell  height  are 
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Character 


Figore  A-7  Character  Cell 

placed  into  celLjwldtli  and  cell  respectively.  For  proportionally 

spaced  fonts,  the  VDI  returns  the  width  of  the  widest  character. 

If  the  requested  size  does  not  exist,  the  VDI  uses  the  closest  charac- 
ter size  that  does  not  exceed  the  requested  size. 

WORD  vst-load_font8  (handle,  select) 

WORD  handle,  select; 

Load  the  fonts  associated  with  a particular  driver.  The  fonts  aie  linked 
to  the  driver  through  the  ASSIGN.SYS  file.  Once  the  file  is  loaded,  the 
fonts  are  available  to  the  workstation  specified  by  handle. 

The  function  returns  the  number  of  nevdy  generated  font  identi- 
fiers. If  the  fonts  were  alreatfy  available  to  the  workstation,  no  action 
occurs  and  the  function  returns  0.  The  select  parameter  Is  reserved 
and  should  always  be  0. 

WORD  vst-point  (handle,  fpoint,  char_wldfh,  char-height, 
cell-widtii,  cell -height) 
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WORD  handle, 

^int, 

*<diar.widt]i,  *diar_hej^t, 

*ceU-widUi,  *celLJieightf 

Set  the  current  text  height  in  pointe.  One  point  is  1/72  of  an  inch.  The 
point  size,  specified  in  tpoint,  is  the  distance  from  the  baseline  of  one 
line  of  text  to  the  baseline  of  the  next  line  of  text  (see  Figure  A-8). 

The  function  sets  char_widfli  and  char  ..height  to  the  character 
width  and  height.  resp>ectively.  The  cell  width  and  cell  height  are 
placed  into  cell-width  and  cell-height,  respectively.  For  proportional^ 
spaced  fonts,  the  VDI  returns  the  width  of  the  widest  character.  Tliese 
values  are  given  in  current  coordinate  units. 

If  the  requested  size  does  not  exist  the  VDI  uses  the  closest  charac- 
ter size  that  does  not  exceed  the  requested  size. 


Character 


Fi£nieA-8  Character  Cell 
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WORD  ^nBt-iotation  (handle,  tetanic) 

WORD  handle, 
tztan^e; 

Set  the  an^e  of  rotation  of  the  character  baseline.  The  angle  of  rota- 
tion. given  in  tntangle,  measures  tenths  of  a degree  and  ranges  from  0 
to  3600.  The  an^e  0 is  the  defoult  text  rotation  and  increasing  angles 
continue  counterclockwise. 

The  basdine  angle  used  is  a best-fit  value.  Some  devices  do  not 
support  text  rotation,  and  other  devices  aUow  onfy  quarter-turn  rota- 
tions (0, 90,  and  270  degrees).  The  function  returns  the  actual  angle  of 
rotation  selected. 

WORD  vBt-imload-lonts  (handle,  select) 

WORD  handle,  select; 

Remove  the  fonts  from  a woikstatlon.  This  function  makes  the  fonts 
loaded  through  the  vst-load-fontsf ) function  unavailable  to  the  work- 
station given  handle.  If  the  fonts  are  being  used  more  than  one 

woikstatlon  with  the  same  physical  device  handle,  the  fonts  are  not 
unloaded  from  memoiy  until  one  of  two  conditions  exists.  Either  all 
workstations  that  share  the  fonts  are  closed,  or  all  workstations  that 
share  the  fonts  request  that  the  fonts  be  unloaded.  The  default  ^tem 
fonts  for  the  workstation  always  remain  loaded  and  available.  The 
parameter  sdcct  is  reserved  and  should  alwEQrs  be  0. 

WORD  vBWT..jiiiode  (handle,  wmode) 

WORD  handle, 
wmode; 


Set  the  writing  mode  for  the  workstation  to  the  value  of  wmode.  Valid 
writing  modes  are: 


Constant 

Value 

Mode 

MD_REPLACE 

1 

Replace 

MD_TE^S 

2 

Transparent 

MD-XOR 

3 

XOR 

MDJBRASE 

4 

Reverse  transparent 

The  resulting  output  on  the  display  is  determined  by  the  output 
pixel  value  (source)  and  the  current  pixel  value  (destination).  The 
following  definitions  are  used: 
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Term 

D^nition 

Mask 

Output  pixel  value  of  the  image 

Fore 

Selected  output  color  pixel  chosen 

Back 

Background  color  pixd  in  use  (color  0) 

Old 

Current  pixel  value 

New 

Resulting  pixel  value 

Replace  mode  simply  outputs  the  Image  regardless  of  the  current 
contents  of  the  display: 

new  = (fore  AND  mask)  OR  (back  AND  NOT  mask) 
Transparent  mode  affects  those  pixels  where  the  Image  Is  to  appear: 
new  = (fore  AND  mask)  OR  (old  AND  NOT  mask) 

XOR  mode  reverses  the  bits  representing  the  colon 
new  = mask  XOR  old 

Reverse  Transparent  mode  affects  those  pixels  where  the  image  does 
not  appean 

new  = (old  AND  mask)  OR  (fore  AND  NOT  mask) 

The  function  returns  the  writing  mode  selected.  The  writing  mode 
stays  in  effect  until  It  is  explicitly  changed.  The  default  writing  mode 
is  Replace. 

VOIDVsyiicO 

Halt  program  execution  until  the  next  vertical  blank  interrupt  This 
function  is  useful  for  synchronizing  graphic  output 

WORD  y_tq>dv^  (handle) 

WORD  handle; 

Update  the  workstation.  This  function  causes  all  pending  graphic 
commands  for  the  workstation  given  by  handle  to  be  executed  imme- 
dlatety.  The  commands  are  executed  in  the  order  in  which  they  were 
placed  In  the  buffer.  For  printer  or  plotter  devices,  this  function  causes 
the  device  drive  to  begin  output  to  the  device.  For  a metafile,  GEM  VDI 
outputs  the  opcode  to  update  the  workstation.  This  function  has  no 
effect  on  screen  devices. 
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WORD  wlnd-calc  (wL.clype,  wi-cUnd, 

wi-cimc,  wi-dny,  wl_cinw,  wi-cinh, 
wi-coutz,  wi_couty,  wLcoutw,  wL-coutli) 

WORD  wi_ctype,  wi-ckind, 

wi-dnz,  wi-dny,  wLcinw,  wi-dnh, 
*wi_coutK,  *wl_couty,  *wi_coutw,  *wi_couth; 


Calculate  the  size  and  position  of  a window’s  border  area  or  work  area. 
When  given  the  work  area,  the  function  calculates  the  border  area. 
When  given  the  border  area,  the  function  calculates  the  work  area.  The 
type  of  information  returned  Is  determined  by  wl_ctype,  where; 


0 = return  border  area  data 

1 = return  work  area  data 

The  bits  of  parameter  wi_ckind  Indicate  the  window  control  areas  to 
Include  in  the  calculation.  See  wi-crUnd  of  function  wind-create( ) for 
the  bit  settings. 

The  Input  area  Is  passed  through  parameters  wi_dnx,  wi_ dny, 
wi-dnw,  and  wi-dnlL.  The  calculated  area  Is  returned  through  param- 
eters wi-couts,  wi_couty,  wi_coutw,  and  wi_couth. 

A returned  value  of  0 Indicates  an  error. 

WORD  wind-dose  (wi-dhandle) 

WORD  wi-cihandle; 


Close  a window  to  remove  it  from  the  screen.  The  window  specified  by 
wi-dhandle  is  removed  from  the  screen.  This  function  only  removes 
the  window  from  visibility.  The  window  is  still  kept  in  the  AES.  A 
returned  value  of  0 indicates  an  error. 

WORD  wind-cieate  (wi-cddnd,  wi-crwx,  wi-crwy,  wi-crww, 
wl crah] 

WORD  wi-crkind. 

wi crwx,  wi ciwy,  wi— crww,  wi uiwh; 

Allocate  the  application’s  full-size  window  and  return  the  window 
handle.  This  function  requests  allocation  of  a window  from  the  AES. 
GEM  on  the  Atari  ST  allows  up  to  eight  windows  to  be  allocated  at  any 
given  time.  The  bits  of  parameter  wi-crUnd  determine  the  window 
components  to  be  displayed  as  follows: 
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Constant 

Value 

Component 

NAME 

0x0001 

Title  bar  with  name 

CLOSER 

0x0002 

Close  box 

FULLER 

0x0004 

Full  box 

MOVER 

0x0008 

Move  box 

INFO 

0x0010 

Information  line 

SIZER 

0x0020 

Size  box 

UPARROW 

0x0040 

Up  arrow 

DNARROW 

0x0080 

Down  arrow 

VSLIDE 

0x0100 

Vertical  slider 

LFARROW 

0x0200 

Left  arrow 

RTARROW 

0x0400 

Right  arrow 

HSLIDE 

0x0800 

Horizontal  slider 

If  the  bit  Is  set  to  1.  the  window  displays  that  component  For  a des- 
cription of  the  components,  see  the  text 
The  parameters  wi-ciwz,  wi_vrwy,  wL.ccww,  and  wi-cndi  define 
the  window’s  position  and  size  when  at  its  largest  size. 

The  returned  value  ranges  finm  0 to  an  environment-specific  value 
(8  on  the  ST).  This  value  Is  the  window  handle  used  by  the  other  Win- 
dow Manager  functions.  If  a negative  value  is  returned,  the  GEM  AES 
has  no  more  windows  available. 

WORD  wind-delete  (wi_dhandle) 

WORD  wLdhandle; 

Delete  a window  finm  the  AES.  When  an  application  no  longer  requires 
the  use  of  a window  (e.g.,  prior  to  exiting  to  the  Desktop),  the  zqrplica- 
tion  should  release  the  allocated  portion  of  the  AES  being  used  to 
maintain  the  window.  The  window  should  also  be  closed  before  it  is 
deleted.  A returned  value  of  0 indicates  an  error. 

WORD  wind-find  (wL-fnuc,  wi-finy) 

WORD  wi-fnix,  wi-fimy: 

Get  the  handle  of  the  first  window  under  the  location  given.  This  func- 
tion locates  the  window  being  displayed  at  the  location  specified 
wi-finx  and  wi-£my  and  returns  the  handle  to  the  window  found,  or  0 
if  it  is  the  Desktop. 

WORD  wind-get  (wt  .ghandle,  wi-gfield. 

wi_gwl,  wi_gw2,  wi-gw3,  wi-gw4) 

WORD  wi-ghandle,  wi-gfield, 

*wi-gwl,  *wi_gw2,  *wi-gw3,  *wi_gw4; 
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Obtain  information  regarding  a window.  This  is  a multi-purpose  func- 
tion. The  window  handle  is  given  by  wL-ghandle.  The  information  is 
returned  through  parameters  wi_gwl,  wi_gw2,  wi_gw3, 2md  wL_gw4. 
The  type  of  information  to  return  is  specified  with  wi-gfield.  The  pre- 
defined constant  names  and  values  and  the  usage  of  the  return 
parameter  are  given  below: 

WF-WORKXYWH  4 

request  the  size  and  position  of  the  window’s  work  area 
wl-gwl:  X coordinate  of  upper  left  comer 
wl-gw2:  y coordinate  of  upper  left  comer 
wl-gw3;  width  of  work  area 
wi-gw4:  height  of  work  area 
WF_CURRXYWH  5 

request  the  size  and  position  of  the  entire  current  window 

induding  control  areas 

wi-gwl:  X coordinate  of  upper  left  comer 
wi-gw2:  y coordinate  of  upper  left  comer 
wi-gw3:  width  of  current  window 
wl-gw4:  height  of  current  window 
WF_PREVXYWH  6 

request  the  window’s  previous  size  and  position 
wi-gwl:  X coordinate  of  upper  left  comer 
wi-gw2:  y coordinate  of  upper  left  comer 
wi_gw3:  width  of  previous  window 
wi-gw4:  height  of  previous  window 
WF_FULLXYWH  7 

request  the  full  window’s  size  and  position 
wi-gwl:  X coordinate  of  upper  left  comer 
wi-gw2:  y coordinate  of  upper  left  comer 
wi-gw3:  width  of  full  window 
wi-gw4:  height  of  full  window 
WF-HSLIDE  8 

request  relative  position  of  horizontal  slider 

wi-gwl:  value  from  0 (furthest  left)  to  100  (furthest 
right) 

WF-VSLIDE  9 

request  relative  position  of  vertical  slider 

wi-gwl:  value  from  0 (top)  to  1000  (bottom) 

WF-TOP  10 

request  the  handle  of  the  active  (topmost)  window 
wi-gwl:  handle  of  active  window 
WFJFTRSTXYWH  11 

request  position  and  size  of  the  first  rectangle  in  the 

window’s  visible  rectan^e  list  (see  text) 
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wi_gwl:  X coordinate  of  upper  left  comer 
wi_gw2:  y coordinate  of  upper  left  comer 
wi-gw3:  width 
wi-^4:  height 
WF_NEXTXYWH  12 

request  position  and  size  of  the  next  rectangle  in  the 
window’s  visible  rectangle  list  (see  text) 

wi_gwl:  X coordinate  of  upper  left  comer 
wi-gw2:  y coordinate  of  upper  left  comer 
wi-gw3:  width 
wi-gw4:  height 
WF-HSLSIZE  15 

request  size  of  the  horizontal  slider 

wl-gwl;  1 to  1000  = size  relative  to  scroll  bar 

— 1 = default  minimum  size  (sqiiare  box) 

WF-VSLSIZE  16 

request  size  of  the  vertical  slider 

wl-gwl:  1 to  1000  = size  relative  to  scroll  her 

— 1 = default  minimum  size  (square  box) 

WF_SCREEN  17 

request  address  and  length  of  the  internal  menu/alert 
buffers 

wi-gwl:  low  WORD  of  address 
wi_gw2:  high  WORD  of  address 
wi-gw3:  low  WORD  of  length 
wi-gw4:  high  WORD  of  length 

A returned  value  of  0 indicates  an  error. 

WORD  wind_open  (wi_<diandle,  wi-owz,  wl-owy,  wL.oww,  wL^owli) 
WORD  wi-ohandle, 

wl— owz,  wi—owy,  wi_oww,  wi_oirfi; 

Open  a window  to  make  it  visible  on  the  screen.  TTie  window  to  open  is 
specified  by  its  handle  given  in  wi_ohandle.  The  initial  position  and 
size  of  the  window  are  given  by  wi-owz,  wi_owy,  wL.oww,  and 
wL-ovdi.  A returned  value  of  0 Indicates  an  error. 

WORD  wind_set  (wi_shandle,  wi-sfield, 

wi_8wl,  wi— sw2,  wi_sw3t  wl— sw4) 

WORD  wi-shandle,  wi_sfield, 

wL.swli  wl_8w2t  wi_»w3,  wi_sw4; 


Change  the  values  in  a window's  field  that  determine  how  the  window 
is  displayed.  The  window  is  specified  by  the  handle  in  wl-ahandle.  The 
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Add  to  change  Is  given  by  wl-sfield  using  the  predefined  constants 
given  bdow.  The  remaining  parameters  hold  the  new  values  for  the 
Add  to  change.  These  parameters  are  defined  asWORDs  but  may  also 
be  used  to  pass  address  pointers.  Because  an  address  requires  two 
WORDS,  a program  may  simply  use  the  address  in  the  parameter  list 
in  place  of  two  WORD  psuameters  (either  wi-swl  and  wi_jsw2  or 
wi_sw3  and  wL-8w4).  For  example,  to  set  the  information  line,  the  call 

wlnd-set  (wi-diandle,  WP-INFO,  info_line): 

could  be  used  where  parameter  info-line  is  a pointer  to  a string.  The 
predefined  constants  and  parameter  usage  are: 

WF_KIND  1 

set  the  components  of  the  window 

wi_swl:  see  wl_crklnd  in  the  wind_create()  function  for 
the  appropriate  bit  settings 

WF_NAME  2 

set  the  name  in  the  title  bar 

wl_swl  and  wi_sw2:  pointer  to  a string 
WF_INPO  3 

set  the  information  line 

wi_swl  and  wi_sw2:  pointer  to  a string 
WF_CURRXYWH  5 

set  the  size  and  position  of  the  entire  current  window 
indudlng  control  areas 

wl_swl:  X coordinate  of  upper  left  comer 
wl_sw2:  y coordinate  of  upper  left  comer 
wl_sw3:  width  of  current  window 
wi_sw4:  height  of  current  window 
WFJHSLIDE  8 

set  the  relative  position  of  horizontal  slider 

wl_swl:  value  from  0 (furthest  left)  to  1000  (furthest 
right) 

WF_VSLIDE  9 

set  the  relative  position  of  vertical  slider 

wi_swl:  value  from  0 (top)  to  1000  (bottom) 

WF_TOP  10 

set  a new  active  (topmost)  window 
wl_swl:  handle  of  active  window 
WFJFIRSTXYWH  14 

set  the  address  of  a new  default  GEM  Desktop  for  the  GEM 
AE^  to  draw 

wl_swl  and  wl_sw2:  address  of  the  object  tree 
wl_sw3:  index  of  starting  object  to  draw 
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WF_HSLSIZE  15 

set  the  size  of  the  horizontal  slider 

wi_swl:  1 to  1000  = size  relative  to  scroll  bar 

~ 1 = default  minimum  size  (square  box) 

WF_VSLSIZE  16 

set  the  size  of  the  vertical  slider 

wi_swl:  1 to  1000  = size  relative  to  scroll  bar 

— 1 = default  minimum  size  (square  box) 

A returned  value  of  0 Indicates  an  error. 

i 

WORD  wind-v^date  (wi-ubegend) 

WORD  wi-ub^end; 

Communicate  with  the  AES  about  the  application’s  current  process- 
ing. This  function  informs  the  AES  of  four  specific  conditions. 
The  condition  is  identified  fay  the  pre-defined  constant  given  in 
wi-ubegend.  The  constants  and  conditions  are  defined: 

END_UPDATE  0 

Notify  the  AES  that  the  application  has  completed  updating 
a window.  The  AE^  again  allows  the  user  to  interact  with 
the  screen. 

BEG_UPDATE  1 

Notify  the  AE^  that  the  application  is  about  to  update  a 
window.  During  the  update,  the  AES  does  not  allow  the 
user  to  Interact  with  the  windows. 

END_MCTRL  2 

Notify  the  AEIS  that  the  application  is  returning  control  of 
all  mouse  functions  to  the  AE^. 

BEG_MCTRL  3 

Notify  the  AES  that  the  application  is  taking  control  of  all 
mouse  functions.  While  the  application  has  control  of  the 
mouse  functions,  the  Screen  Manager  does  not  respond  to 
mouse  input  and  menus  and  window  control  are  not 
active  unless  handled  by  the  application. 

The  function  returns  0 if  an  error  condition  exists. 

VOID  Xb timer  (tlmeraet,  ctrlreg.  data,  vec) 

WORD  timerset  ctrlreg,  data; 

WORD  (*vec)(); 

Set  the  timers  on  the  68301  MFP  (multi-fun<^on  peripheral).  The 
timer  to  set  is  given  by  timerset.  An  8-bit  value  for  the  timer  control 
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register  is  given  by  ctrlr^.  The  8 bit  data  value  for  the  timer  data 
register  is  given  by  data.  The  new  Interrupt  vector  Is  given  by  vec. 
Refer  to  the  68901  for  details  of  Its  operation. 


GEM  DOS  Functions 


Cauxln 

Cauxls 

Cauxos 

Cauxout 

Cconin 

Cconis 

Cconos 

Coonout 

Cconrs 

Cconws 

Cnecin 

Cpmos 

Cpmout 

Crawcin 

Crawlo 

Dcreate 

Ddelete 

Dfree 

Dgerdrv 

Dge^th 

Dstdrv 

Dse^ath 

Fattrib 

Fclose 

Fcreate 

Pdatime 

Fdelete 

Fdup 

Fforce 

Fgetdta 

Fopen 

Fread 

Frename 

Fseek 

Fsetdta 

Fsflrst 

Fsnext 

Pwrlte 

Malloc 


Read  character  from  AUX; 

Check  status  of  AUX:  Input 
Check  status  of  AUX:  output 
Write  character  to  AUX: 

Read  character  standard  Input 

Check  status  of  standard  input 

Check  status  of  standard  output 

Write  character  to  standard  ou^ut 

Read  edited  string  from  standard  input 

Write  string  to  standard  Input 

Read  character  from  standard  Input,  no  echo 

Check  status  of  PRN: 

Write  character  to  PRN: 

Raw  input  from  standard  input 

Raw  I/O  with  standard  Input/ou^ut 

Create  directory 

Delete  directory 

Get  drive  free  space 

Get  default  drive 

Get  current  directory 

Set  default  drive 

Set  current  path 

Get  or  set  file  attributes 

Close  file 

Create  file 

Get  or  set  file  time  stamp 
Delete  file 

Duplicate  file  handle 

Force  file  handle 

Get  disk  transfer  address  (DTA) 

Open  file 
Read  from  file 
Rename  file 
Seek  file  pointer 
Set  DTA 

Search  for  first  file 
Search  for  next  file 
Write  to  file 
Allocate  memory 
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Mfree 

Mshrlnk 

Pexec 

Ptenn 

PtennO 

Ptermres 

Super 

Sversion 

Tgetdate 

Tgettime 

Tsetdate 

Tsettime 


Release  memoiy 

Shrink  size  of  allocated  block 

Load  and  execute  process 

Terminate  process  with  exit  code 

Terminate  process  with  exit  code  0 

Terminate  and  stay  resident 

Get  set  or  inquire  supervisor  mode 

Get  GEM  version  number 

Get  date 

Get  time 

Set  date 

Set  time 


GEM  BIOS  Fnnctioiis 


Bconln 

Bconout 

Bconstat 

Bcostat 

Drvmsq) 

Getbpb 

Getmpb 

Kbshlft 

Medlach 

Rwabs 

Setexc 

Tlckcal 


Input  from  character  device 
Output  to  character  device 
Get  character  device  input  status 
Get  status  of  output  device 
Get  map  of  active  drives 
Get  BIOS  parameter  block 
Get  memoiy  parameter  block 
Get  or  set  keyboard  shift  bits 
Check  for  media  change 
Read  or  write  block  on  a device 
Set  exception  vector 
Get  ^tem  timer  calibration 


Atari  ST  Extended  BIOS  (XBIOS)  Functions 


Bioskeys 

Cursconf 

Dosound 

Flophnt 

Floprd 

Flopver 

Flopwr 

Getrez 

Gettime 

Giaccess 

Ikbdws 

Inltmous 

lorec 

Jdisint 

Jenabint 

Kbrate 


Restore  keyboard  translation  tables 
Configure  terminal  cursor 
Set  sound  daemon  program  counter 
Format  track  on  floppy  drive 
Read  from  floppy  drive 
Verify  sectors  on  floppy  drive 
Write  to  floppy  drive 
Get  screen’s  current  resolution 
Get  time  and  date 

Read  or  write  registers  on  sound  chip 

Write  string  to  intelligent  keyboard 

Initialize  mouse  packet  handler 

Get  address  of  serial  device  buffer  records 

Disable  interrupt  on  MFP 

Enable  interrupt  on  MFP 

Get  or  set  keyboard’s  repeat  rate 
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Kbdvbase 

KQTtbl 

Logbase 

Mfpint 

Midiws 

Offglbit 

Ongiblt 

Physbase 

Protobt 

Puntaes 

Random 

Rsconf 

Scrdmp 

Setcolor 

Selpalette 

Selprt 

Setscreen 

Settime 

Supexec 

Xbtimer 


Get  keyboard  device  packet  vectors 

Set  k^rboard  translation  tables 

Get  screen’s  logical  base  address 

Set  MFP  interrupt  number 

Write  string  to  MIDI  port 

Clear  Port  A bit  on  sound  chip 

Set  Port  A bit  on  soimd  chip 

Get  screen’s  physical  base  address 

Prototype  a boot  sector 

Throw  away  AES 

Generate  a random  number 

Configure  RS232  port 

Dump  screen  to  printer 

Set  color  raster  in  palette 

Set  hardware  color  palette 

Set  or  get  printer  configuration  t^e 

Set  screen  addresses  and  resolution 

Set  time  and  date 

Execute  code  in  supervisor  mode 

Walt  for  vertical  blank  interrupt 

Set  MFP  timer  control 


AES  i^4>plication  Manager  Functions 


appl_exit 

appl_find 

2^pl_inlt 

appl-read 

appl_tplay 

appl-trecord 

appl-write 


Exit  sqipllcation  from  AES 
Locate  the  ID  of  another  application 
Initialize  application  to  AE^ 

Read  from  the  message  pipe 

Play  GEM  AES  recording  of  user’s  actions 

Record  user’s  actions 

Write  to  the  message  pipe 


AES  Event  Blanager  Functions 


evnt_button 

evnt-ddick 

evnt-keybd 

evnt_mesag 

evnt_mouse 

evnt_multl 

evnt-tlmer 


Wait  for  mouse  button  event 
Get  or  set  double-dick  speed 
Wait  for  keyboard  event 
Walt  for  message  event 
Walt  for  mouse  event 
Walt  for  multiple  events 
Walt  for  timer  event 


AES  File  Selector  Manager  Function 

fsd-input  Display  file  selector  dialog  box 
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AES  Form  Manager  Functions 


form-alert 

form_center 

form-dial 

form-do 

form-error 


Display  alert  box 
Center  dialog  box  on  screen 
Prepare  screen  for  dialog  box 
Monitor  user  Interactions  with  form 
Display  error  box 


AES  Graphics  Manager  Functions 


graf-dragbox 

graf-growbox 

graf-handle 

graf-mbox 

graf-mkstate 

graf-mouse 

graf-rubbeibox 

graf-shrlnkbox 

graf-slidebox 

graf-watchbox 


Draw  and  track  moving  box 

Draw  an  expanding  box 

Get  VDI  handle  for  screen  workstation 

Draw  a moving  box 

Return  current  mouse  state 

Change  mouse  form 

Draw  and  track  rubber  box 

Draw  a shrinking  box 

Track  sliding  box  in  its  parent 

Track  a watch  box 


AES  Menu  Manager  Functions 


menu-bar 

menu_icheck 

menu-lenable 

menu-T^ister 

menu-text 

menu-tnormal 


Display  or  erase  the  menu  bar 

Display  or  erase  check  mark  In  menu  item 

Display  menu  item  as  enabled  or  disabled 

Register  desk  accessory  with  AEIS 

Change  text  of  menu  item 

Display  menu  title  in  reverse  or  normal  video 


AES  Object  Manager 


objc_add 

objc-change 

objc-delete 

objc-draw 

objc-edit 

objc-flnd 

objc-offset 

objc-order 


Add  object  to  an  object  tree 

Change  an  object's  state 

Delete  an  object  from  an  object  tree 

Draw  an  object  or  object  tree 

Let  user  edit  text  object 

Locate  object  under  mouse 

Compute  object’s  location  relative  to  the  screen 

Change  the  order  of  an  object  within  the  tree 


AEIS  Resource  Manager 

rsrc-free  Remove  resource  file  from  memory 

rsrc-gaddr  Get  the  address  of  a data  structure  in  memory 


C Function  Reference  Guide  477 


rsrc-load 

rsrc-obflx 

rsrc-saddr 


Load  a resource  file  into  memory 
Convert  object’s  x and  y coordinates 
Store  the  address  of  a data  structure 


AES  Scn^p  Manager 

scrp_read  Read  the  scrap  directory  in  the  clipboard 

scrp_write  Write  the  scr£^  directory  to  the  clipboard 


AES  Shell  Manager 


sheLenvron 

shel-find 

shel-iead 

shel-write 


Search  environment  for  parameter 
Locate  a filename 

Identify  the  command  that  invoked  the 
application 

E^t  AES  or  run  another  s^plication 


AES  Window  Manager 


wind-calc 

wind-dose 

wind-create 

wind-ddete 

wind-find 

wind-get 

wind-open 

wind-set 

wind-update 


Calculate  window  area 

Close  an  open  window 

Allocate  window  and  obtain  handle 

Remove  window  from  AES 

Locate  window  under  given  coordinates 

Get  window  values 

Open  a created  window 

Set  window  values 

Notify  AE^  about  window  updating 


VDI  Control  Functions 


v-clrwk 

v-dsvwk 

v-dswk 

v-opnvwk 

v-opnwk 

v-updwk 

vst-load-fonts 

vst-unload-fonts 

vs-dip 


Clear  workstation 
Close  virtual  workstation 
Close  workstation 
Open  virtual  workstation 
Open  workstation 
Update  workstation 
Load  fonts  for  device 
Remove  fonts  for  device 
Set  clipping  rectangle 


VDI  Output  Functions 

v_arc  Arc 

v-bar  Bar 
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v_clrde 

Circle 

v_cdlarray 

Cell  array 

v_contourflU 

Contour  fill 

v_ellarc 

Elliptical  arc 

v_elllpse 

Ellipse 

v-dlpie 

Elliptical  pie 

v-fUlarea 

Fill  area 

v_gtext 

Graphics  text 

v_justlfled 

Justified  graphics  text 

v_pieslice 

Pie 

v_pline 

Pofy-Unes 

v_pmarker 

Pofy-markers 

v_rix)x 

Rounded  rectangle 

v_rfbox 

Filled  rounded  rectangle 

vr_recfl 

Filled  rectangle 

VDI  Attribute  Functions 

vs_color 

Set  color  representation 

vsf_color 

Set  fill  color 

vsf_interior 

Set  interior-fill  stjde 

vsf_perlmeter 

Set  fill  perimeter  visibility 

vsf-sljde 

Set  fill  style  index 

vsf_udpat 

Set  user-defined  fill  pattern 

vsL-color 

Set  poly-line  color  index 

vsl_ends 

Set  poly-line  end  stjdes 

vsLtype 

Set  poly-line  line  type 

vsLudsly 

Set  user-defined  line  style  pattern 

vsl_widtii 

Set  poly-line  line  width 

vsm_color 

Set  poly-marker  color  index 

vsm_height 

Set  poly-marker  height 

vsm_type 

Set  poly-marker  type 

vst-alignment 

Set  gTE^hics  text  alignment 

vst_color 

Set  graphics  text  color  index 

vst_efifects 

Set  graphics  text  effects 

vst-font 

Set  text  face 

vst_hei^t 

Set  character  height,  absolute 

vst_point 

Set  character  height,  points 

vst-Totation 

Set  character  baseline  rotation 

vswr_mode 

Set  writing  mode 

VDI  Raster  Functions 

v_get_plxel 

Get  pixel 

vro_cpyfm 

Copy  raster,  opaque 
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vrt-qpyfin  Copy  raster,  transparent 

vr_trnfm  Transform  form 


VDI  Input  Functions 


vex_butv 

vex_curv 

ve3C_motv 

vex_timv 

v_hlde_c 

vq_mouse 

vq_kqr_s 

vrq_choice 

vrq-locator 

vrq_string 

vrq.valuator 

vsc-form 

v_show_c 

vsin_mode 

vsm_choice 

vsm_locator 

vsm-strlng 

vsm_valuator 


Exchange  button  change  vector 
Exchange  cursor  change  vector 
Exchai^e  mouse  movement  vector 
Exchange  timer  interrupt  vector 
Hide  cursor 

Sample  mouse  button  state 
Sample  kqdxiard  state  Information 
Input  choice,  request  mode 
Input  locator,  request  mode 
Input  string,  request  mode 
Input  valuator,  request  mode 
Set  mouse  form 
Show  cursor 
Set  input  mode 
Input  choice,  sample  mode 
Input  locator,  sample  mode 
Input  string,  sample  mode 
Input  valuator,  sample  mode 


VDI  Inquire  Functions 


vq_cellarray 

vq_color 

vq.extnd 

vqf_attrlbutes 

vqin_mode 

vql_attrlbutes 

vqm-attrlbutes 

vqt_attributes 

vqt_extent 

vqt_fontlnfo 

vqt_name 

vqt_wldth 


Inquire  cell  array 

Inquire  color  representation 

Extended  inquire 

Inquire  fill  area  attributes 

Inquire  input  mode 

Inquire  poty-line  attributes 

Inquire  poty-maiicer  attributes 

Inquire  current  graphics  text  attributes 

Inquire  text  extent 

Inquire  current  face  information 

Inquire  face  name  and  ind&c 

Inquire  character  cell  width 


VDI  Escape  Functions 

V-bit-image  Output  bit  image  file 

v-clear_dlsp_llst  Clear  display  list 
v_curdown  Alpha  ciusor  down 
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v-curhome 

Home  Alpha  cursor 

v_curieft 

Alpha  cursor  left 

v_curright 

Alpha  ciusor  right 

v_cnrtext 

Output  cursor  addressable  alpha  text 

v_curup 

Alpha  cursor  up 

v_dspcur 

Place  graphics  cursor  at  location 

v_eeol 

Erase  to  end  of  alpha  text  line 

v_eeos 

Erase  to  end  of  alpha  screen 

v_enter_cur 

Exit  alpha  mode 

v_exit_cur 

Enter  alpha  mode 

v_form_adv 

Form  advance 

v_hardcopy 

Hard  copy 

v_meta_extents 

Update  metafile  extents 

vm-fUename 

Chemge  GEM  VDl  file  name 

1 

1 

s 

1 

Ou^ut  window 

vq_chcells 

Inquire  addressable  alpha  character  cells 

vq_curaddress 

Inquire  current  alpha  cursor  address 

vq-tabstatus 

Inquire  tablet  status 

v-rmcur 

Remove  last  graphics  cursor 

v_rvoff 

Reverse  video  off 

v_rvon 

Reverse  video  on 

vs-curaddress 

Direct  alpha  cursor  address 

APPENDIX  B 


Header  Files 


This  appendix  contains  the  source  code  listings  for  the  header  files 
mentioned  in  this  book.  These  flies  are  used  by  the  Megamax  C 
compiler  and  the  Atari  development  ^tem.  Depending  upon  the 
compiler  and  the  version  of  GEM  3rou  are  using,  you  may  And  a few 
changes  to  these  header  flies.  When  using  the  programs  in  this  book, 
if  you  get  compiler  errors  indicating  undefined  constants  or  function 
names,  you  should  compare  the  header  flies  you  are  using  with  the 
ones  listed  here.  Then  make  the  appropriate  changss  to  your  header 
flies  or  the  program  flies. 

GBMBIND.H 

y*  GEMBIND.H  Do-It-Yoursolf  GEM  binding  kit* 

y*  Copyright  1385  Atari  Corp* 


y*  CRANING:  This  flis  is  not  supported!  *y 

y*  Ue  reccomend  you  use  the  supplied  binding  libraries  *y 

y*  Application  Manager  *y 

ttdefine  RPPL_INIT  10 
ttdefine  RPPL_RERD  11 
ttdefine  RPPL_WRITE  12 
ttdoflne  RPPL_FIND  13 
ttdefine  RPPU.TPLRY  14 
ttdefine  RPPL-TRECORD  15 
ttdefine  RPPL_EXIT  19 


ttdefine  EVNTJ<EYBO  20 
ttdefine  EVNT_BUTTON  21 


y*  Event  Manager 


ttdefine  EVNT-MOUSE  22 
ttdefine  EVNT_MESRG  23 
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ttdefine  EVNT-.TIMER  24 
ttdefine  EVNTJ1ULTI  25 
ttdefine  EVNT-DCLICK  26 

ttdefine  MENU-BRR  30 
ttdefine  MENO_ICHECK  31 
ttdefine  MENLUIENflBLE  32 
ttdefine  MENU^TNORMflL  33 
ttdefine  MENLL.TEXT  34 
ttdefine  MENLLREGISTER  35 

ttdefine  OBJCLRDO  40 
ttdefine  OBJCLDELETE  41 
ttdefine  OBJCJ^RRU  42 
ttdefine  OBJC-TIND  43 
ttdefine  OBJCJDFFSET  44 
ttdefine  OBJCJDROER  45 
ttdefine  OBJCLXDIT  46 
ttdefine  0BJCJCH6NGE  47 

ttdefine  FORN_DO  50 
ttdefine  FDRMLDIftL  51 
ttdefine  FDRM-ftLERT  52 
ttdefine  F0R^L£RRDR  53 
ttdefine  FORM-CENTER  54 
ttdefine  FORM-KEYBD  55 
ttdefine  FORM-BUTTON  56 

ttdefine  GRRF-RUBBOX  70 
ttdefine  GRRFJ)RPGBOX  71 
ttdefine  GRRF-MBOX  72 
ttdefine  GRRFJGROUBOX  73 
ttdefine  GRRF-SHRINKBDX  74 
ttdefine  GR6F-URTCHBDX  75 
ttdefine  GRRFJ5LIDEBOX  76 
ttdefine  GRflF_HftNDLE  77 
ttdefine  GRRF-MOUSE  78 
ttdefine  GRftF-MK5TflTE  79 

ttdefine  SCRP-READ  B0 
ttdefine  SCRP-WRITE  01 

ttdefine  FSEL^INPUT  90 

ttdefine  UINDjCREATE  100 
ttdefine  1<IIND_0PEN  101 
ttdefine  NINDJCLOSE  102 
ttdefine  NIND-OELETE  103 
ttdefine  UINO-GET  104 
ttdefine  MINDSET  105 
ttdefine  UIND-FIND  106 
ttdefine  UINDJUPDRTE  107 
ttdefine  UINDJCRLC  10B 


Menu  Manager 
Object  Manager 


Form  Manager 


/*  Graphics  Manager 


Scrap  Manager 

File  Selector  Manager 
Window  Manager 


Resource  Manager 


Header  Pile  483 


Itdaflne  RSRC-i.OftO  110 
ndeflne  RSRC_FREE  111 
((define  RSRC-CftOOR  112 
((define  RSRC-SflODR  113 
((define  RSRC-DBriX  114 

/» 

((define  SHEL-RERO  120 
((define  SHEI-URITE  121 
Itdaflne  SHELJGET  122 
((define  SHEI—PUT  123 
((define  SHEL-TIND  124 
((define  SHEL-ENVRN  125 

ttdafine  Il-SIZE  A 
ttdaflna  (U5IZE  15 
ttdafine  I-SIZE  16 
ttdafina  CLJ5IZE  7 
ttdafine  RIJ5IZE  2 
ttdafine  RQJ5IZE  1 

ttdefina  OPJCODE  control [0] 
ttdafine  INJ.EN  control [1] 
ttdafine  OUTJ.EN  control(2] 
ttdafina  RIhLLEN  control [3] 

ttdafine  RETJCCDE  int-jout[0J 

ttdafina  RP^VERSIQN  global [0] 
ttdafine  RPJ:0UNT  giobai[l] 
ttdafine  RP.I0  giobai[2] 
ttdafine  RP^OPRIVRTE  giobai[3] 
ttdafina  RP^IPRIVRTE  global[4] 
ttdafine  fiP-lOPNRME  global [S] 
ttdafina  RP^IPNRUE  global [6] 
ttdafine  RPJ.01RESV  global [7] 
ttdafine  RP^IIRESV  global [0] 
ttdafine  RPJ.02RESV  global [9] 
ttdafina  RP^I2RESV  global [10] 
ttdafina  RP^03RESV  global  [11] 
ttdefina  RP-HI3RESV  global[12] 
ttdafine  RPJ.04RESV  global[13] 
ttdafine  RP^I4RESV  global  [14] 

ttdefina  RP J5LSIZE  int^ut[l) 

ttdafine  RP^UID  int^n[0] 
ttdefina  RP-LENBTH  lnt-ln[lj 
ttdafine  fiP-PBUFF  addr_ln[0J 

ttdefina  RP^NRME  addr.in[0] 

ttdafine  RP-TBUFFER  addr..ln[0] 
ttdefina  RP-TLENBTH  lnt-in[0] 
ttdafine  RP_JSCRLE  int_in[l] 


Shall  Manager 

max  sizes  for  arrays 
Crystal  funtion  op  code 


application  lib  parameters 

long  ptr.  to  tree  base  in  rsc*^ 

long  address  of  memory  alloc. 

length  of  memory  allocated 
colors  av/ailable  on  screen 
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ttdafins  SCR-MGR  0x0001  /*  pid  of  the  screen  manager^^/ 

ttdeflne  RPJ1SG  0 
ttdefine  tIM-SELECTED  10 

Udeflne  UM_REDRRU  20 
ltdefine  WM_TDPPED  21 
ttdefina  WM_J:lOSED  22 
ttdeflna  WM-FULLED  23 
tidafine  UM.RRRDMED  24 
ttdeflne  WMLHSLID  25 
ttdeflne  UM_V5LID  26 
ttdeflna  UN-SIZED  27 
ttdeflna  UN-NOVED  20 
ttdeflne  UN-NEUTDP  29 

ttdeflne  RCUJPEN  40 
ttdeflne  RCJCL05E  41 

ttdeflne  .CTJJPDRTE  50 
ttdeflne  CTJ10VE  51 
ttdeflne  CT_NEWTOP  52 

event  11b  parameters 

ttdeflne  IN_FLRGS  lnt_ln[0] 

ttdeflne  B-CLICK5  lnt_ln[0] 
ttdeflne  B-NfiSK  lnt_ln[l] 
ttdeflne  B_STRTE  lnt_ln[2] 

ttdeflne  MOlFLRGS  lnt_ln[0] 
ttdeflne  KO-X  lnt-ln[l] 
ttdeflne  MD_V  lnt_ln[2] 
ttdeflna  MCUJIDTH  lnt-ln[3] 
ttdeflne  MD-HEIGHT  lnt^n[4] 

ttdeflne  NE-PBUFF  addr_ln[0] 

ttdeflne  T_LOCOUNT  lnt.an[0] 
ttdeflne  T-HICDUNT  lnt^n[l] 

ttdeflne  MU-FLRGS  lnt-ln[0] 
ttdeflne  EV-MX  Int-outtl] 
ttdeflne  EVJ1Y  lnt-out[2] 
ttdeflne  EV-MB  int-Dut[3] 
ttdeflne  EV-KS  lnt-out[4] 
ttdeflne  EV-KRET  lnt^ut[5] 
ttdeflna  EV-BRET  lnt^ut[6] 

ttdeflne  MB-CLICKS  lnt_ln[l] 
ttdeflna  MB-MR5K  int-ln(2] 
ttdeflne  MB-STRTE  lnt-ln[3] 
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ttdBfine  MMDl_fLflGS  int_ln[4] 

((define  MMOl-X  lnt-ln[5] 

((define  nnai_Y  lnt_ln(6] 

((define  MMOl-WIOTH  lnt_ln[7] 

((define  MMOl-HEIGHT  lnt_ln[B] 

((define  MM02_FLflGS  lnt_ln[9] 

((define  MM02-X  lnt_ln(10] 

((define  nn02_V  lnt-ln[ll] 

((define  Hn02-MI0TH  lnt_ln(12] 

((define  MM02_HEIGHT  lnt_ln[13] 

((define  nnE-PBUrr  addr_ln[0] 

((define  (1T_L0CCUNT  lnt_ln[14] 

((define  (1T_HICOUNT  lnt_ln[lS] 

mu-flags 

ttdefine  MLi-XEYBD  0x0001 
ttdefine  tIUJBUTTON  0x0002 
ttdefine  MlUll  0x0004 
ttdefine  niLJ12  0x0008 
ttdefine  MIUIESRG  0x0010 
ttdefine  t1LL.TIt1ER  0x0020 


ttdefine  EV«DCRftTE  int.an[0] 
ttdefine  EVJJCSETIT  int_in[l] 

menu  library  parameters 


ttdefine 

MtUTREE 

addr_in[0] 

/* 

ienabie,  ichecl<«  tnorm 

ttdefine 

MtU^STR 

addr.in[0] 

ttdefine 

MM-PTEXT 

addr.in[l] 

ttdefine 

SHOW-JT 

lnt_in[0] 

/» 

bar 

ttdefine 

ITEfOCUM 

int-in[0] 

/* 

icheck,  ienabie 

ttdefine 

WMJ3ID 

int—in(0] 

/* 

register 

uy 

ttdBfine 

CHECK-JT 

int-in[l] 

/* 

i check 

ttdefine 

ENRBLE-IT 

int--in[l] 

ienabie 

»/ 

ttdefine 

TITLE-NUW 

int_in[0] 

tnorm 

ttdefine 

NDRMRLJtT 

int_in[l] 

tnormal 

form  library  parameters 

ttdefine  rM-TORM  addr«ln[0] 
ttdefine  FMJSTfiRT  int-in[0] 


ttdefine  FM-TYPE  int.an[0] 
ttdefine  FM-ERRNUM  int-in[0] 
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^define  FM_J)EFBUT  int_in[0] 
ttdBflne  FM_flSTRING  addr_inl0] 

ttdefine  FM^IX  int— in[l] 
ttdefine  FM_jy  int«ln[2] 
ttdefine  FN_IU  int-in[3) 
ttdBfine  FM«IH  int_ln[4] 
ttdBfina  FM-X  int«in[S] 
ttdBflna  FM_Y  int-in[6] 
ttdBfina  FM-W  int_in[7) 
ttdBfina  FM_H  int_ln[B] 

ttdafina  FM_XC  lnt^ut[l] 
ttdBfina  FM-YC  int__Dut[2] 
ttdBfina  FMJJC  lnt__out[3] 
ttdafina  FM-HC  lnt_out[4] 

ttdBfina  FMD_STfiRT  0 
ttdBfins  FMD_GROW  1 
ttdBfins  FMDJ5HRINK  2 
ttdBfina  FMD_FINISH  3 


ttdeflna  DB-.TREE  addr^n[0] 

ttdBfina  OBJDELOB  lnt-ln[0] 

ttdsflnB  OB-DRAUOB  lnt_ln[0] 
ttdBfina  DBJ)EPTH  lnt.ln[l] 
ttdafina  OB-XCLIP  int«ln[21 
ttdafina  OB^YCLIP  int— in[3] 
ttdafina  DB-WCLIP  int-in[4] 
ttdefine  OB-KCLIP  int_in[5] 

ttdBfina  DB-STftRTOB  int_ln[0] 
ttdefine  OBJDEPTH  int_in[l] 
ttdafina  OB-MX  int«ln[2] 
ttdafina  OB—tlY  int^n[3] 

ttdafina  OB-PRRENT  int_in[0] 
ttdafina  OBJCHILD  int_in[l] 
ttdafine  OBJDBJ  lnt_in[0] 
ttdafina  OBOCOFF  int^ut[l] 
ttdafina  0B.Y0FF  int_jout[2] 
ttdafina  0B_KEUP0S  int.in[l] 


ttdafina  OBJCHPR  int_lntl] 
ttdafina  DB^IOX  int_in[2] 
ttdafina  DB_KIND  int«inI3] 
ttdefine  0B_DDX  int_out[l] 


object  library  parametars 
ail  cb  procedures 
y'*  oh  rieiata 

ob^rau,  ob_changa  / 


ob—find 


y*  ob^dd 

ob-offaet,  ofcLJorder 

ob^rdar 
/»  cb^adit 
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ndeflne  OB_NEUSTflTE  int-ln[6) 
ttdefine  QB^EORRU  int.ln[7] 

ltdefine  GR.J1  lnt-an[0] 
ltdafine  GR— 12  lnt^ln[l] 
ttdefine  GR-I3  lnt_ln[2] 
ttdefine  GR_I4  lnt_ln[3] 
ttdefine  6R.IS  lnt.ln[4] 
ttdefine  GR^IG  lnt.ln[5] 
ttdefine  GP_I7  lnt.ln[G] 
ttdefine  GRJB  lnt.ln[7] 

ttdefine  GR-01  Int  nut[l] 
ttdefine  GR-02  lnt^ut[2] 

ttdefine  GR-TREE  addr_ln[0] 
ttdefine  GR_PfiRENT  lnt_ln[0] 
ttdefine  GR^BJ  lnt.ln[l] 
ttdefine  GR_INSTflTE  lnt_ln[2) 
ttdefine  GR-OUTSTfiTE  lnt-ln[3] 

ttdefine  GR_ ISVERT  lnt^n[2] 

ttdefine  MJDFF  25G 
ttdefine  tUDN  257 


/*  ob^hange 

graphics  library  parameters 


ttdefine  GR-JINUhBER  lnt^n[0] 
ttdefine  GRJ1RDDR  addr^n[0] 

ttdefine  GR-MCHRR  lnt_^ut[l] 
ttdefine  GR-HCHRR  lnt_out[2] 
ttdefine  GR-t4BDX  lnt_out[3] 
ttdefine  GR-HBOX  lnt^ut[4] 


ttdefine  GR.J1X  lnt_out[l] 
ttdefine  GR^Y  lnt^ut[2] 
ttdefine  GR-J1STRTE  lnt-out[3] 
ttdefine  GR-KSTRTE  lnt^ut[4] 

ttdefine  SC-PRTH  addr_ln[0] 


ttdefine  FS_IPRTH  addr^n[0] 
ttdefine  FS-ISEL  addr«ln[l) 


/*  scrap  library  parameters 
file  selector  library  parms 


ttdefine  FS^liTTON  lnt^ut[l] 

ttdefine  XFULL  0 

ttdefine  YFULL  gl_hbox 

ttdefine  UFULL  gl-wldth 

ttdefine  HFULL  (gl_helght  - gl_hbox) 


uilndou  library  parameters 
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ttdsfine  NRME  0x0001 
Hdsfine  CLOSER  0x0002 
ttdsflne  FULLER  0x0004 
ttdsflne  MOVER  0x0000 
lids  fine  INFO  0x0010 
lldsflne  SIZER  0x0020 
Itdeflne  UPRRRQM  0x0040 
lldeflne  DNRRRD14  0x0000 
tldeflne  VSLIDE  0x0100 
lldeflne  LFRRRQ14  0x0200 
lldeflne  RTRRRQU  0x0400 
lldeflne  HSLIOE  0x0000 


ttdeflne  WF_KIND  1 
lldeflne  WF_NRME  2 
lldeflne  WF-INFO  3 
tldeflne  WF^XVWH  4 
tldeflne  WFJ:XYWH  5 
tldeflne  WF«PXYWH  6 
tldeflne  WF_FXYWH  7 
tldeflne  WF_HSLIDE  0 
tldeflne  WF_VSLIDE  9 
tldeflne  WF_TOP  10 
tldeflne  WF-FIRSTXYMH  11 
tldeflne  WFJMEXTXYWH  12 
tldeflne  WF-IGNORE  13 
lldeflne  UF_NEWDESK  14 
lldeflne  UFJSLSI2  IS 
tldeflne  WF_VSLSIZ  16 

tldeflne  UR-UPPRGE  0 
tldeflne  Wfl_DNPRGE  1 
tldeflne  WR-UPLINE  2 
tldeflne  Ufl_DNLINE  3 
tldeflne  WR_LFPRGE  4 
tldeflne  Wft_RTPRGE  5 
tldeflne  WR_LFLINE  6 
lldeflne  WflJRTLINE  7 

tldeflne  UM_KIND  lnt-ln[0] 

tldeflne  WPLXRNDLE  lnt_an[0J 

tldeflne  UfLNX  lnt.ln[l] 
tldeflne  WM_WY  lnt_ln[2J 
tldeflne  UM_WW  lnt_ln[3J 
tldeflne  UM_WH  lnt_ln(4| 

tldeflne  UIUIX  lnt_ln(0J 
tldeflne  WM_MY  lnt«ln(lj 

tldeflne  UC-BQRDER  0 
tldeflne  UCJ40RK  1 
tldeflne  WM_WCTYPE  lnt_ln(0J 


arrou  message 


uciLJcreate 

uciLjopsn,  close,  del 

um_Dpen,  um_create 

wtn_flnd 

unujcalc 
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ttdefina  UH_MCKIND  lnt_in[l] 
ttdeflne  UM-UCIX  lnt_in[2] 
ttdoflne  WIUJCIY  int_ln[3] 
ddefine  UM_UCIU  lnt_ln[4] 
ttdeflne  UM-UCIH  lnt_in[5] 
Ddefino  UIOICOX  int^ut[X] 
ttdefina  Uri-MCOY  int^ut[2] 
ttdefina  14rU4COU  int^ut[3] 
ttdefina  UM31C0H  int^ut[4] 

ttdefina  UM-fiEGUP  int^n[0] 

ttdefina  UM_WFIELD  int_in[l] 

ttdefina  WM_IPRIVflTE  int_in[2J 

ttdafine  UM-IKIND  int_an[2] 

ttdefina  MM_IOTITLE  addr-in[0] 

ttdafine  Un_IX  int_in[2] 
ttdefine  WM_IV  int_in[3) 
ttdafine  Ut*LJU  int_in[4] 
ttdafine  int-Jn[5] 

ttdafine  MM-OX  int_out(l] 
ttdafine  UlUDY  int^ut[2] 
ttdafine  UIUDU  int-jout[3] 
ttdefine  I4IU1H  int^ut[4] 

ttdafine  UI>t_ISLIDE  int_in[2] 

ttdefine  UI1-IRECTNUM  int_in[6] 


ttdafine  RS^FNRME  addr^n[0] 
ttdefine  RS_TYPE  int-in[0] 
ttdafine  RS^NDEX  int^n[X] 
ttdefina  RS-INRDDR  addr_in[0] 
ttdafine  RSJDUTRDDR  addr^ut[0] 

ttdefina  R5.TREE  addr_ in[0] 
ttdefina  R5JDBJ  int^n[0] 

ttdefine  R.TREE  0 
ttdefina  RJDBJECT  X 
ttdefina  RL.TEOINFO  2 
ttdafine  R^CONBLK  3 
ttdefine  RJBITBLK  A 
ttdefina  R^TRING  5 
ttdafine  R^MRGEDRTR  6 
ttdafine  RJBSPEC  7 


unuupdate 


for  name  and  info 


raeourca  iibrary  parameters 


r8-Jnit« 
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Bdaflne  R_TEPTEXT  B 
ttdaflna  R-TEPTMPLT  9 
Itdaflna  R_TEPVPLI0  10 
ttdaflna  R_IBPMPSK  11 
ttdaflna  R_IBPDPTA  12 
ttdaflna  R_IBPTEXT  13 
ttdaflna  R-BIPDPTR  14 
ttdaflna  R-FRSTR  IS 
ttdaflna  R_FRinG  16 


/»  sub  ptrs  In  TEDINFD 


/»  sub  ptPS  In  ICONBLK  »/ 


/*  sub  ptrs  In  BITBLK 

•r»  gats  addr  of  ptr  to  frea  strings 

•r»  gats  addr  of  ptr  to  fraa  Imagss  »<' 


<'»  shall  library  paramatsrs 

ttdaflna  SH-DOEX  lnt_ln(0] 
ttdaflna  SH_IS6R  lnt_ln(l] 
ttdaflna  SH-ISCR  lnt_ln[2] 

Itdaflna  SH-PCMD  addr_ln(0] 
ttdaflna  SH_PT«IL  addr_ln(l] 


ttdaflna  SHLPDflTR  addr_ln(0] 
ttdaflna  SH_PBUFFER  addr_ln[0) 


Itdaflna  SH.LEN  lnt-ln[0] 


Itdaflna  SH_PRTH  addr_ln[0] 
Itdaflna  SH-5RCH  addr_ln[l] 


GEMDBFS.H 


GEMDEFS.H  Common  GEM  dofinitions  and  miscellaneous  structures. 

Copyright  1305  fttarl  Corp.  */ 

/««»»«««»»«««««««««««»»«»««««««««»»»«««»«»«»»««»»»««««««««««««««»«««»««««/ 


/»  EVENT  Manager  Definitions 

ttdefine  MUJ<EYBD  0x0001 
ttdefine  MU^BUTTQN  0x0002 
ttdafine  MU^l  0x0004 
ttdefine  MU^2  0x0008 
ttdefina  MU^ESRG  0x0010 
Udefine  MU.TIMER  0x0020 

ttdefine  K-PSHIFT  0x0001 
ttdefine  KJLSHIFT  0x0002 
ttdaflna  KJCTRL  0x0004 
ttdefine  K_J)LT  0x0000 

ttdefine  MNJ5ELECTED  10 
ttdefine  UIU2E0RRU  20 
ttdefine  WM-.T0PPED  21 
ttdefine  I4MJCL05ED  22 
ttdofins  WM_FULLED  23 
ttdefine  UMlJ)RRONED  24 
ttdefine  WM-HSLID  25 
ttdefine  UM_VSLID  26 
ttdefine  WMLSIZED  27 
ttdefine  UMJ1DVE0  28 


multiflags  */ 


keyboard  states 


message  values 


Header  File  491 


itdeflne 

UM-NEUTQP 

29 

ttdefine 

fiCJDPEN 

40 

Udeflne 

RCJCLOSE 

41 

/» 

FORK  Manager  Definitions 

Form  flags 

tide  fine 

FMDJ5TRRT 

0 

Udefine 

FMDJGRG14 

1 

ltdefine 

FMD-SHRINK 

2 

ttdefine 

FMD-FINISH 

3 

RESOURCE  Manager  Definitions 

data 

1 structure  types 

Udefine 

R.TREE 

0 

Udefine 

RJDBJECT 

1 

Udefine 

R-TEDINFO 

2 

Udefine 

R-iCDNBLK 

3 

Udefine 

R-BITBLK 

4 

Udefine 

R-J5TRING 

5 

gets  pointer  to  free  strings 

Udefine 

R^MRGEORTR  6 

gets  pointer  to  free  images 

Udefine 

RJ3BSPEC 

7 

Udefine 

R-TEPTEXT 

6 

/*  sub  ptrs  in  TEDINFO 

*/ 

Udefine 

R-TEPTMPLT 

3 

Udefine 

R-TEPVRLID 

10 

Udefine 

RLJBPMRSK 

11 

sub  ptrs  in  ICQNBLK 

Udefine 

R^BPDRTR 

12 

Udefine 

R-IBPTEXT 

13 

Udefine 

R_flIPDRTfl 

14 

/*  sub  ptrs  in  BITBLK 

Udefine 

R-JRSTR 

IS 

gets  addr  of  ptr  to 

free  strings 

»/ 

Udefine 

R^RIMG 

16 

gets  addr  of  ptr  to 

free  images 

*/ 

used  In  RSCRERTE.C 

typedaf  struct  rshdr 
< 


int 

rsh^wrsn; 

int 

rsh-i3bjact; 

int 

rsh_tadinfo; 

int 

rsh_iconbik; 

list  of  ICONBLKS 

int 

rsKJiitbik; 

int 

rsh«frstr; 

int 

rsK-strlng; 

int 

rsh^mdata; 

image  data 

int 

rsh— frimg; 

int 

rsh.tr index; 

int 

rsh.nobs; 

counts  of  various  structs 

int 

rsh.ntree; 

int 

rsKjnted; 

int 

rsh-nib; 

int 

rsh.nbb; 

int 

rsh-nstring; 

int 

rsh^nimages; 

int 

rsh.rssize; 

total  bytes  in  resource 

> RSHDR: 

ttdafine  F-RTTR  0 

file  attr  for  dos.crsate 
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WINDOW  Manager  Definitions 

Windoy  Pttributes 

ttdafine  NRME  0x0001 
ttdefine  CLOSER  0x0002 
»define  FULLER  0x0004 
Udefine  MOVER  0x0008 
ttdefine  INFO  0x0010 
ttdefine  SIZER  0x0020 
ttdefine  UPRRROW  0x0040 
ttdefine  DNRRROW  0x0080 
ttdefine  VSLIDE  0x0100 
ttdefine  LFRRROW  0x0200 
ttdefine  RTRRROW  0x0400 
ttdefine  HSLIDE  0x0800 

yincLxreate  flags  */’ 

ttdefine  WO^ORDER  0 
ttdefine  WC3I0RK  1 

y*  yincL^et  fiage 

ttdefine  WF-KIND  1 

ttdefine  WF^RME  2 

ttdefine  WFJNFO  3 

ttdefine  WF^ORKXYWH  4 

ttdefine  WF^URRXYWH  5 

ttdefine  WF-PREVXYWH  6 

ttdefine  WF^ULLXYWH  7 

ttdefine  WF_HSLIOE  8 

ttdefine  WF.VSLIOE  3 

ttdefine  WF_TOP  10 

ttdefine  WF_FIRSTXYWH  11 

ttdefine  WF_NEXTXYWH  12 

ttdefine  WFJ^ESVO  13 

ttdefine  WF.NEWOESK  14 

ttdefine  WFJHSLSIZE  IS 

ttdefine  WF.VSLSIZE  16 

ttdefine  WFJ5CREEN  17 

update  fiags 

ttdefine  ENOaJPDRTE  0 
ttdefine  BEGJUPDRTE  1 
ttdefine  ENOJ1CTRL  2 
ttdefine  BEG-MCTRL  3 


y*  GRRPHICS  Manager  Definitions 

ttdefine  PRROU  0 
ttdefine  TEXTJCRSR  1 
ttdefine  H0UR6LRSS  2 
ttdefine  POINT_HRND  3 
ttdefine  FLRT-HRND  4 
ttdefine  THINJCROSS  5 
ttdefine  THICKJCR05S  6 
ttdefine  OUTLNJCROSS  7 
ttdefine  USER-DEF  255 
ttdefine  MJDFF  256 
ttdefine  M-ON  257 


»/ 

Mouse  Forms 
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<'•  MISCELLRNEOUS  Structures 

Momopy  Form  Definition  Block 

typGdof  struct  fdbstr 

{ 

long  fd-addr; 

Int  fd-ju; 

Int  fdLh; 

Int  fd-uduldth; 

Int  fd  .stand; 

Int  fdLnplanss; 

Int  fd— rl; 

Int  fd— t2; 

Int  fd-r3; 

1 FOB; 

Mouse  Form  Definition  Block 

typedef  struct  mfstr 

{ 

Int  mf-^hot; 

Int  fflf^hot; 

Int  (nf_nplanes; 

Int  mf— fg; 

Int  fflfJbg; 

Int  fflf— fflask[16] ; 

Int  mf-data(16] ; 

> MFORM; 

OBDOS.H 

ItdeFlne  ROOT  0 

lldeflne  KflXJ_EN  81  max  string  length 

ttdeflne  MflXJBEPTH  8 max  depth  of  search  or  draw 

ttdaflne  IP-HOLLOU  8 Inside  patterns 

ttdeflne  IP-lPftTT  1 

ttdeflne  IP-2P8TT  2 

ttdeflne  IP-3P8TT  3 

ttdeflne  IP-4P8TT  4 

ttdeflne  IP-5P8TT  5 

ttdeflne  IP-JBPflTT  6 

ttdeflne  IP_JSOLID  7 

ttdeflne  MD—REPL8CE  1 gsx  modes 

ttdeflne  MD-TRANS  2 
ttdeflne  MD-XOR  3 
ttdeflne  MD-ERA5E  4 

ttdeflne  ftLI I4HITE  0 bit  bit  rules 

ttdeflne  S-RND-D  1 
ttdeflne  S-RND-NDTD  2 
ttdeflne  S_DNLY  3 
ttdeflne  NOTS-RND-D  4 
ttdeflne  DJDNLY  5 
ttdeflne  5-XOR-D  6 
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ttdofine  SJDR-D  7 
ttdefine  NOT^ORD  8 
ttdefinB  NDT-SXORD  9 
ttdefine  D-INVERT  10 
ttdofine  N0T_D  11 
ttdofine  SJDR_NDTD  12 
ttdofine  NDTS_DR_D  13 
ttdofine  NOT^RNDD  14 
ttdofine  PLL^LRCK  15 

ttdofine  IBM  3 font  types 

ttdofine  SMRLL  S 

ttdofine  6_B0X  20  Graphic  types  of  obs 

ttdofine  G-TEXT  21 

ttdofine  G-BOXTEXT  22 

ttdofine  G.IMR6E  23 

ttdofine  G-PROGDEF  24 

ttdofine  G-IBOX  25 

ttdofine  G-BUTTON  26 

ttdofine  G^OXCHRR  27 

ttdofine  GJ5TRING  26 

ttdofino  G-FTEXT  29 

ttdefino  G-FBOXTEXT  30 

ttdofine  GUCON  31 

ttdefino  G-TITLE  32 

ttdofine  NONE  0x0  Object  flags 

ttdofine  SELECTR8LE  0x1 

ttdefino  DEFRULT  0x2 

ttdefino  EXIT  0x4 

ttdefino  EDITRBLE  0x8 

ttdefine  RBUTTON  0x10 

ttdofine  LRSTOB  0x20 

ttdefine  TOUCHEXIT  0x40 

ttdefine  HIOETREE  0x80 

ttdefine  INDIRECT  0x100 

ttdefine  NORMRL  0x0  Object  states 

ttdefine  SELECTED  0x1 

ttdefine  CROSSED  0x2 

ttdefine  CHECKED  0x4 

ttdefine  D1SR8LED  0x8 

ttdefine  OUTLINED  0x10 

ttdefine  SHRDONED  0x20 

ttdefine  WHITE  0 Object  colore 

ttdefine  8LRCK  1 

ttdefine  RED  2 

ttdefine  GREEN  3 

ttdefine  BLUE  4 

ttdefine  CVRN  5 

ttdefine  YELLOW  6 
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lldeflne  MftGENTR  7 
Odefine  LI4HITE  B 
Ddeflne  LBLRCK  9 
ttdBflne  LRED  10 
ttdeflne  L6REEN  11 
ttdeflne  LBLUE  12 
ttdBflna  LCYRN  13 
ItdBfinB  LYELLQU  14 
OdBflnB  LMRGENTR  15 

ttdBflriB  EDSTRRT  0 Bditabla  tsxt  flBld  daflnltions 

OdBflnB  EDINIT  1 
OdBflnB  EDCHRR  2 
Odaflne  EDEND  3 

OdeflnB  TEJLEFT  0 Bdltabls  tBxt  Justification 

OdBflnB  TE-RIGHT  1 
OdBflnB  TEJCNTR  2 


StructurB  Daflnltlons 


typBdaf  struct  object 

< 

Int  ob^Bxt;  ->  object's  next  sibling 

Int  ob-head;  ->  head  of  object's  children 

Int  ob_tall;  ->  tail  of  object's  children 

unsigned  Int  ob_type;  type  of  object-  BOX,  CHRP, 

unsigned  Int  ob-.flags;  flags 

unsigned  Int  cb^tate;  y*  state-  SELECTED,  OPEN,  ... 
char  *ob.jBpec;  y*  “out“-  ->  anything  else  *y 

Int  ob_x;  /*  upper  left  corner  of  object 

Ant  ob_y;  y*  upper  left  corner  of  object  *y 

Int  obuuildth;  y*  uldth  of  obj  *y 

int  ob_helght;  y*  height  of  obJ  *y 

} OBJECT; 


typadef  struct  orect 
{ 


Struct 

orect  *o-Jink; 

Int 

o-^; 

int 

o-jy; 

lot 

o— u; 

Int 

o_h; 

> ORECT; 


typedef  struct 

greet 

{ 

Int 

g_x; 

Int 

Int 

Int 

g_h; 

> 6RECT; 
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typedef  struct  text^dinfo 

{ 

char  ^te^text; 
char  *t8_ptfnplt; 
char  *tG-pv;alid; 
Int  ts^font; 

Int  te-Junkl; 

Int  te^ust; 

Int  te-color; 

Int  te^unk2; 

Int  te^thickness; 
Int  te.txtlen; 
int  t8.tmplen; 

> TEOINFD; 

typsdaf  struct  icon_i]lack 

( 

int  *ib_pmask; 
int  *ib  .pdata; 
char  *ib-ptext; 
int  Ih  rhar; 
int  ib-xchar; 
int  ib^char; 
int  ib_xicon; 
int  ib_yicon; 
int  ibuuiicon; 
int  ibJiicon; 
int  ib^text; 
int  ib^text; 
int  ib^text; 
int  ib-htext; 

} ICONBLK; 

typedef  struct  bit-iilock 

{ 

int  *bi^data; 
int  bi_ub; 

int  bi^l; 

int  bi^; 

int  bijy; 

int  bi_coior; 

> BITBLK; 

typedef  struct  appi-bik 

< 

int  (*ub-jcodB)() ; 
long  ub— parm; 

> APPLBLK; 

typedef  struct  parmJbik 

( 

OBJECT  »pb_tree; 
int  pb_obJ ; 


ptr  to  text  (must  be  1st) 

ptr  to  template 

ptr  to  uaiidation  chrs.  »>’ 

font 

Junk  uord 

Justification-  loft,  right 

color  information  uord 
Junk  uord 

/*  border  thickness 

length  of  text  string 
length  of  template  string 


/*  ptr  to  bit  forms  data 

uidth  of  form  in  bytes 
height  in  linos 
/*  source  x in  bit  form 
/*  source  y in  bit  form 
fg  color  of  bit 
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int  pb-prev/state; 

int  ph  rurrstate; 

int  pb_x«  pkMI,  pb^«  ph_h; 

int  pb_xc«  pb^c,  pb-uc,  pbJnc; 

iong  pb-parm; 

> PftRiieLK; 

STDIO.H 

ItifndBf  -BUFSIZE 


ltdefine  -BUFSIZE  512 
Itdefine  -NFILE  73 


typadef  struct  — iobuf  { 
char  *^tr; 
int  ^nt; 
char  ^Jaase; 
int  —flag; 
int  —fd; 

long  —mark;  position  relative  to  start  of  file  of  —base 

int  -bufsize;  buffer  size  for  this  file 

) FILE; 

extern  FILE  _lob(_NFILEl; 


ndefine  stdin  (&— iob(0]) 
^define  stdout  (&— iob(l]) 
ndefine  stderr  (&— iob(2]) 


ndefine 

-REftD 

01 

ndefine 

-WRITE 

02 

ndefine 

-APPEND 

04 

ndefine 

-UNBUF 

010 

ndefine 

-BI6BUF 

020 

ndefine 

-LINBUF 

0400 

ndefine 

JEOF 

040 

ndefine 

JERR 

0100 

ndefine 

-DIRTY 

0200 

ndefine 

NULL  0L 

must 

Udefine  EOF  (-1) 


buffer  uas  changed  *>' 
be  long  since  it  can  be 


passed  as  a parameter 


ttdefine  getc(p)  ( -- (p)->-jcnt  >=  0 ? *(p)->— ptr++  & 0377  : — fillbuf(p)) 
ttdefine  getchar()  gatc(stdin) 

tidefine  putc(x,p)  ( — (p)->-cnt  >=  0 ? (*(p)->_ptr++  = (x))  & 0377  : ^ 
— f lushbuf ( (x) ,p) ) 
tidefine  putchar(x)  putc(x, stdout) 

^define  feof(p)  ( (p)->_fiag&-£OF) 

ttdefine  ferror(p)  ( (p) f lag&-£RR) 

ndefine  clearerr(p)  ((p)->_ flag  &=  '(—ERR  | —EOF)) 

ndefine  fileno(p)  ((p)->— fd) 

ndefine  abs(x)  ( (x)<0?- (x) : (x) ) 

ndefine  rand( ) (int)(^eed  = -seed  * £907  + 130253) 
ndefine  srand(x)  —seed  = x; 


498  Atari  ST 


extern  FILE  *fopen(); 

extern  long  ftell(); 

extern  char  *gets(); 

extern  char  *fgets(); 

extern  char  *malloc(),  ^callacO; 

extern  long  —seed; 

typedef  long  Jmp_buf[5]; 

ttendif 

CTYPE.H 

ttlfndaf  -tolouer 

tldeflne  — tolouer(c)  c+32 
ttdeflne  _ toupper(c)  c-32 

ttdeflne  isalpha(c)  (c>='R'  &&  c<='2‘  ||  c>a'a'  &&  c<='z') 
ttdeflne  Isupper(c)  (c>='R'  &&  c<='2‘) 

ttdeflne  islouer(c)  (c>='a‘  &&  c<='z*) 

ttdeflne  isdlglt(c)  (c>='0‘  &&  c<='9') 

ttdeflne  isalnum(c)  (isalpha(c)  ||  Isdlglt(c)] 

ttdeflne  Isspace(c)  (c=='  ' )|  ca='Nt*  )|  C=='  ‘ |)  c=='Nn‘  }|  c==*Nf*) 

ttdeflne  Ispunct(c)  (c>=‘  ' &&  !lsalnum(c)) 

ttdeflne  Isprlnt(c)  (0=040  &&  c<=0176) 

ttdeflne  Iscntrl(c)  (c>=0  &&  (c==0127  ||  c< ' ')) 

ttdeflne  lsa8cll(c)  (0=0  &&  c<0200) 

ttendif 


ERRNO.H 

extern  Int  errno; 


defined  In  exlt.c 


APPENDIX  C 

KQTcode  Values 


In  text-based  computer  environments,  the  computer  and  operating 
tem  would  encode  each  alphanumeric  character  vrith  a particidar 
value.  Whether  in  a data  file,  on  a communication  line,  or  from  the 
keyboard,  a particular  value  could  be  interpreted  as  the  appropriate 
character.  The  most  popular  mapping  of  numbers  to  characters  for 
personal  computers  is  called  A^II  (American  Standard  Code  for 
Information  Interchange).  ASCII  uses  7 of  the  8 bits  in  a l^e.  This 
defines  128  characters  for  use  the  computer. 

Recentty,  mamy  personal  computers  (including  the  Atari)  have  de- 
fined graphic  characters  to  the  remaining  128  characters  that  can  be 
represented  by  one  t^e  (one  byte  can  represent  256  different  values). 
Unfortunatety,  these  characters  are  generally  a hodge-podge  of  pic- 
tures like  smiling  faces,  Greek  or  Hebrew  letters,  and  so  on.  and  they 
are  hardty  standardized  from  one  computer  to  the  next  On  top  of  this, 
there  are  now  more  than  256  possible  keystrokes  that  can  be  pressed 
by  the  user,  such  as  combinations  with  the  Control.  Shift  and  Alter- 
nate keys  with  the  rest  of  the  keyboard. 

To  alleviate  this  problem  of  understanding  the  data  from  the  user, 
the  GEM  VDI  defines  a set  of  16-bit  values  to  represent  the  keystrokes 
entered  by  the  user.  The  16  bits  are  divided  into  two  l^es.  If  the  char- 
acter is  part  of  the  ASCII  set,  the  low  b3rte  contains  the  ASCII  value. 
Otherwise  it  has  the  value  of  0.  For  example,  the  letter  “A”  has  an 
ASCII  value  of  65.  so  its  low  byte  has  the  t^ue  of  65.  The  high  b3de 
contains  an  arbltraiy  value  assigned  1^  the  VDI  to  differentiate  the 
various  keys  on  the  keyboard.  Below  is  a table  containing  the  high  and 
low  byte  values  and  the  keystrokes  required  to  create  this  kQrcode.  The 
values  shown  are  in  hexadecimal 
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VDI  Standaid  Kqrcode 


Values 

High 

Byte 

Low 

Byte 

Keystroke 

03 

00 

Control  2 

IE 

01 

Control  A 

30 

02 

Control  B 

2E 

03 

Control  C 

20 

04 

Control  D 

12 

05 

Control  E 

21 

06 

Control  F 

22 

07 

Control  G 

23 

08 

Control  H 

17 

09 

Control  1 

24 

OA 

Control  J 

25 

OB 

Control  K 

26 

OC 

Control  L 

32 

OD 

Control  M 

31 

OE 

Control  N 

18 

OF 

Control  0 

19 

10 

Control  P 

10 

11 

Control  0 

13 

12 

Control  R 

IF 

13 

Control  S 

14 

14 

Control  T 

16 

15 

Control  U 

2F 

16 

Control  V 

11 

17 

Control  W 

2D 

18 

Control  X 

15 

19 

Control  Y 

2C 

lA 

Control  Z 

lA 

IB 

Control  [ 

2B 

1C 

Control  \ 

IB 

ID 

Control  1 

07 

IE 

Control  6 

OC 

IF 

Control  — 

39 

20 

Space 

02 

21 

1 

28 

22 

// 

04 

23 

# 

05 

24 

$ 

06 

25 

% 

08 

26 

& 

28 

27 

1 

QA 

28 

( 

OB 

29 

) 

09 

2A 

• 

OD 

2B 

< 

33 

2C 

, 

OC 

2D 

> 

34 

2E 

, 

35 

2F 

/ 
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High  Low 

Byte Byte Keystroke 

OB  30  0 

02  31  1 

03  32  2 

04  33  3 

05  34  4 

06  35  5 

07  36  6 

08  37  7 

09  38  8 

OA  39  9 

27  3A 

27  3B  ; 

33  3C  { 

OD  3D  = 

34  3E  } 

35  3F  ? 

03  40  4» 

IE  41  A 

30  42  B 

2E  43  C 

20  44  D 

12  45  E 

21  46  F 

22  47  G 

23  48  H 

17  49  I 

24  4A  J 

25  4B  K 

26  4C  L 

32  4D  M 

31  4E  N 

18  4F  O 

19  50  P 

10  51  Q 

13  52  R 

IF  53  S 

14  54  T 

16  55  U 

2F  56  V 

11  57  W 

2D  58  X 

15  59  Y 

2C  5A  Z 

lA  5B  I 

2B  5C  s 

IB  5D  ] 

07  5E 

OC  5F  _ (Underscore) 
29  60 
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(coiUbuied) 


High 

Byte. 

Low 

Byte 

Keystroke 

IE 

61 

a 

30 

62 

b 

2E 

63 

c 

20 

64 

d 

12 

65 

e 

21 

66 

f 

22 

67 

g 

23 

68 

h 

17 

69 

i 

24 

6A 

j 

25 

6B 

k 

26 

6C 

1 

32 

6D 

m 

31 

6E 

n 

18 

6F 

0 

19 

70 

P 

10 

71 

q 

13 

72 

r 

IF 

73 

s 

14 

74 

t 

16 

75 

u 

2F 

76 

V 

11 

77 

w 

2D 

78 

X 

15 

79 

y 

2C 

7A 

z 

lA 

7B 

{ 

2B 

7C 

1 

IB 

7D 

} 

29 

7E 

-- 

OE 

7F 

Delete 

81 

00 

Alternate  0 

78 

00 

Alternate  1 

79 

00 

Alternate  2 

7A 

00 

Alternate  3 

7B 

00 

Alternate  4 

7B 

00 

Alternate  5 

7D 

00 

Alternate  6 

7E 

00 

Alternate  7 

7F 

00 

Alternate  8 

80 

00 

Alternate  9 

IE 

00 

Alternate  A 

30 

00 

Alternate  B 

2E 

00 

Alternate  C 

20 

00 

Alternate  D 

12 

00 

Alternate  E 

21 

00 

Alternate  F 

22 

00 

Alternate  G 

23 

00 

Alternate  H 
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(continued) 


High 

Byte 

Low 

Byte 

Keystroke 

17 

00 

Alternate  I 

24 

00 

Alternate  J 

25 

00 

Alternate  K 

26 

00 

Alternate  L 

32 

00 

Alternate  M 

31 

00 

Alternate  N 

18 

00 

Alternate  0 

19 

00 

Alternate  P 

10 

00 

Alternate  Q 

13 

00 

Alternate  R 

IF 

00 

Alternate  S 

14 

00 

Alternate  T 

16 

00 

Alternate  U 

2F 

00 

Alternate  V 

11 

00 

Alternate  W 

2D 

00 

Alternate  X 

15 

00 

Alternate  Y 

2C 

00 

Alternate  Z 

3B 

00 

FI 

3C 

00 

F2 

3D 

00 

F3 

3E 

00 

F4 

3F 

00 

F5 

40 

00 

F6 

41 

00 

F7 

42 

00 

F8 

43 

00 

F9 

44 

00 

FIO 

54 

00 

Fll 

55 

00 

F12 

56 

00 

F13 

57 

00 

F14 

58 

00 

F15 

59 

00 

F16 

5A 

00 

FI  7 

5B 

00 

F18 

5C 

00 

F19 

5D 

00 

F20 

5E 

00 

F21 

5F 

00 

F22 

60 

00 

F23 

61 

00 

F24 

62 

00 

F25 

63 

00 

F26 

64 

00 

F27 

65 

00 

F28 

66 

00 

F29 

67 

00 

F30 

68 

00 

F31 
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(continued) 


High 

Byte 

Low 

Byte 

Keystroke 

69 

00 

F32 

6A 

00 

F33 

6B 

00 

F34 

6C 

00 

F35 

6D 

00 

F36 

6E 

00 

F37 

6F 

00 

F38 

70 

00 

F39 

71 

00 

F40 

73 

00 

Control  left  arrow 

4D 

00 

Right  arrow 

4D 

36 

Shift  right  arrow 

74 

00 

Control  right  arrow 

50 

00 

Down  arrow 

50 

32 

Shift  down  arrow 

48 

00 

Up  arrow 

48 

38 

Shift  up  arrow 

51 

00 

Page  down 

51 

33 

Shfit  page  down 

76 

00 

Control  page  down 

49 

00 

Page  up 

49 

39 

Shift  page  up 

84 

00 

Control  page  up 

77 

00 

Control  home 

47 

00 

Home 

47 

37 

Shift  home 

52 

00 

Insert 

52 

30 

Shift  insert 

53 

00 

Delete 

53 

2E 

Shift  delete 

72 

00 

Control  print  screen 

37 

2A 

Print  screen 

01 

IB 

Escape 

OE 

08 

Bactepace 

82 

00 

Alternate  — 

83 

00 

Alternate  + 

1C 

OD 

Carriage  return 

1C 

OA 

Control  carriage  return 

4C 

35 

Shift  numeric  pad  5 

4A 

2B 

Numeric  pad  — 

4£ 

2B 

Numeric  pad  + 

OF 

09 

Tab 

OF 

00 

Backtab 

4B 

00 

Left  arrow 

4B 

34 

Shift  left  arrow 

4F 

00 

End 

4F 

31 

Shift  end 

75 

00 

Control  end 
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S3^tem  Variables 


The  Atari  ST  Basic  Input/Output  System  (BIOS)  uses  a set  of  variables 
that  define  various  characteristics  of  the  computer.  These  variables 
reside  at  specific  locations  in  memoiy.  Atari  has  guaranteed  that  these 
memory  locations  will  not  change  with  future  revisions  to  the  ST 
BIOS.  Therefore,  if  a program  needs  to  access  this  Information,  it  will 
always  be  able  to  find  it  at  the  same  location  on  any  ST  machine.  In 
order  to  read  to  or  write  from  these  addresses,  the  program  must  be  in 
Supervisor  mode. 

The  list  below  gives  the  address,  length,  name,  and  description  of 
each  locatiorL  The  name  is  the  common  variable  name  used  to  refer- 
ence this  location.  For  convenience,  most  programmers  use  the  vari- 
able names  given  here  when  working  with  the  particular  location. 

NOTE:  The  information  presented  here  is  for  completeness  and 
general  reference.  Those  readers  who  do  not  have  experience  in  work- 
ing with  operating  systems  should  avoid  changing  any  of  these  values. 
If  you  want  to  use  any  of  these  variables,  you  should  obtain  the  com- 
plete Atari  ST  documentation  before  continuing. 

System  Variables 

etv—timer  long  0x400 

System  Timer  interrupt  vector.  Eivery  50  Hz,  the  routine  pointed  to 
by  this  value  is  called  to  maintain  the  system's  date  and  time  of  day. 
This  is  the  same  vector  as  the  GEMDOS  logical  vector  0x100,  Timer 
Tick. 


etv-ditlc 


long  0x404 
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Critical  Error  Handler  vector.  This  location  points  to  an  error  han- 
dling routine  for  certain  error  (e.g.,  disk  errors  and  media  changes). 
This  is  the  same  vector  as  the  GEMDOS  logical  vector  0x101,  Critical 
Error  Handler. 

etiT_teim  long  0x408 

Process  Terminate  vector.  Tlie  routine  pointed  to  by  this  value  is 
called  when  a process  terminates.  Tliis  is  the  same  vector  as  the 
GEMDOS  logical  vector  0x102,  Terminate  Handler. 

etv-ztia  5 long  0x40C 

Each  long  value  is  a pointer  to  a routine  corresponding  to  the 
GEMDOS  logical  vectors  0x103  through  0x107.  These  vectors  are 
reserved  for  use  by  later  versions  of  GEMDOS. 

memvalid  long  0x420 

This  location  holds  the  value  0x752019F3.  This  value  is  used  in  con- 
junction with  location  memval2  to  verify  a successful  cold  start  (that 
is,  power  on  or  pushing  the  reset  button). 

memcntlr  t^e  0x424 

The  value  at  this  address  contains  the  value  used  to  configure  the 
memoiy  controUer.  The  low  four  bits  at  this  location  specify  the 
memoiy  la}rout  Some  common  values  are: 


Memory  size 

Value 

128K 

0 

512K 

4 

256K  (2  banks) 

0 

1MB  (2  banks) 

5 

resvalid  long  0x426 

If  this  location  contains  the  number  0x31415926  on  a ^tem 
RESET,  Intern  execution  jumps  to  the  location  in  lesvector. 

resvector  long  0x42A 

System  RESET  trap  vector.  See  description  for  resvalid. 

ph3nstop  long  0x42E 

The  value  here  is  the  address  of  the  physical  end  of  RAM.  This  is  the 
address  of  the  first  unusetble  b}rte  (e.g.,  0x80000  on  a 512K  machine). 

-membot  long  0x432 
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This  location  contains  the  address  of  the  bottom  of  available 
memoiy.  The  GEM  BIOS  Getmpb( ) function  uses  this  value  as  the 
start  of  the  transient  program  areas  (TPA). 

.memtop  long  0x436 

Top  of  available  memoiy.  The  GEM  BIOS  Getmpbf ) function  uses 
this  value  as  the  end  of  the  TPA 

memval2  long  0x43A 

This  location  contains  the  nvimber  0x237698AA  See  memvalid. 

flock  WORD  0x43E 

Locks  usage  of  the  direct  memoiy  access  (DMA)  chip.  A nonzero 
value  indicates  that  the  DMA  is  in  use. 

seekrate  WORD  0x440 

Default  floppy  disk  seek  rate.  Only  bits  0 and  1 are  used.  Th^  have 
the  following  meanings: 


Bits 

Time 

00 

6 ms 

01 

12  ms 

10 

2 ms 

11 

3 ms  (default) 

-timer-ms  WORD  0x442 

System  timer  calibration  in  milliseconds  (ms).  This  value  is  usually 
set  a 0x14  (20  decimal).  The  value  Is  returned  by  the  GEM  BIOS  func- 
tion tickcalf ). 

-fverify  WORD  0x444 

Floppy  disk  verify  flag.  A zero  value  here  means  that  no  verification 
is  done  for  writing  operations.  A nonzero  value  means  that  all  write 
operations  to  floppy  disks  are  verified  through  a read.  Verification  on 
is  the  default 

-bootdev  WORD  0x446 

The  number  of  the  device  used  to  boot  the  ^tem. 
palmode  WORD  0x448 

Video  mode  flag.  A nonzero  value  indicates  that  the  PAL  mode  (50 
Hz  video)  is  in  use.  A zero  value  means  that  the  NTBC  mode  (60  Hz 
video)  is  in  use. 


de&hiftmd 


byte  0x44A 
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This  value  indicates  the  color  resolution  to  use  if  the  system  is 
forced  to  switch  from  a monochrome  monitor  to  a color  monitor. 

sdiiftind  WORD  Qx44C 

This  value  is  equal  to  the  current  setting  for  the  screen  resolution 
hardware  register.  The  values  have  the  following  interpretations: 


0 320  X 200  X 4 (low  resolution  color) 

1 640  X 200  X 2 (medium  resolution  color) 

2 640  X 400  X 1 (high  resolution  monochrome) 


-v-base-ad  long  0x44E 

Address  of  the  ph3rsical  screen  memory.  This  value  points  to  a 
continuous  block  of  32,000  bytes  that  starts  on  a half-page  (256  b)rte) 
boundary. 

vblaem  WORD  0x452 

A semaphore  (mutual  exclusion  flag)  to  ensure  that  onty  one  process 
at  a time  uses  the  vertical-blank  interrupt  handler.  A value  of  one 
allows  vertical  blank  processing. 

nvbls  WORD  0x454 

Number  of  pointers  in  the  vertical-blank  queue.  This  value  is  set  to  8 
on  system  R^E)T. 

-vblqueue  long  0x456 

This  variable  points  to  a list  of  pointers  to  routines  used  as  vertical- 
retrace  handlers.  All  of  the  handlers  are  executed  at  each  vertical 
retract  Interrupt. 

coloiptr  long  0x45A 

A pointer  to  a color  palette.  This  variable  points  to  an  array  of  16 
WORDS  that  define  the  color  palette.  The  eirray  is  loaded  during  the 
next  vertical  retrace.  If  coloiptr  contains  the  NULL  value,  no  palette  is 
loaded.  A NULL  is  placed  into  colorptr  after  the  palette  is  loaded. 

BCieenptr  long  0x45E 

The  address  of  the  new  physical  screen  memoiy.  During  the  next 
vertical  retrace,  the  address  in  screenpt  is  loaded  into  -v-bas-ad,  then 
a NULL  is  placed  into  screenpt.  A NULL  value  indicates  no  change  to 

-v-bas-ad. 

-vbdock  long  0x462 

A count  of  the  number  of  vertical-blank  interrupts  that  have  oc- 
curred since  the  last  ^tem  RESET. 


\ 


System  Variables  509 


_frclock  long  0x466 

The  number  of  vertical  retrace  interrupts  that  were  processed  (i.e., 
not  blocked  by  vblsem). 

hchr-init  long  0x46A 

A pointer  to  the  hard  disk  initialization  routine.  This  will  be  NULL  if 
it  is  not  used. 


swv-vec  long  0x46E 

The  address  of  a routine  that  is  executed  when  the  monitor  is  ph3rs- 
icalty  changed  (i.e.,  when  the  monochrome  monitor  is  plugged  or 
vmplugged).  Default  address  is  the  qratem  RESET  routine 

hdv-bpb  long  0x472 

The  address  of  a routine  that  returns  the  BIOS  parameter  block 
(BPB)  for  a hard  disk.  A NULL  value  indicates  that  this  location  is 
imused.  This  routine  uses  the  same  parameters  and  return  values  as 
the  GEM  BIOS  function  Geibpb( ). 

hdv_rw  long  0x476 

The  address  to  the  routine  that  reads  from  and  writes  to  the  hard 
disk.  A NULL  indicates  tmused.  The  parameters  and  return  values  are 
the  same  as  the  Rwabs( ) GEM  BIOS  function. 

hdv_boot  long  0x47A 

The  address  of  the  routine  to  boot  from  the  hard  disk  (NULL  if 
unused). 

hdv_mediadi  long  0x47E 

The  address  of  the  routine  to  detect  if  a change  in  the  hard  disk’s 

media  See  GEM  BIOS  function  Mediach( ). 

-cmdload  WORD  0x482 

A nonzero  value  tells  the  system  to  tiy  to  load  and  execute  the  pro- 
gram COMMAND.PRG  from  the  boot  device.  The  boot  sector  can  set 
this  location  to  nonzero  so  that  an  application  may  be  loaded  instead 
of  the  GEM  Desktop. 

conterm  t^e  0x484 

The  bits  in  this  location  determine  the  console  attributes  as  follows: 


Bit Function 

0 1 = enable  audible  key  click 

1 1 = enable  auto  kqr  repeat 

2 1 = ring  bell  when  ASCII  value  7 is  sent  to  CON: 

3 1 = return  the  current  value  of  kbshift  in  bits 
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24-31  when  Bconin( ) is  called.  See  GEM  BIOS  function  Kbshiftf ). 
themd  long  0x48E 

Address  of  a memory  descriptor  structure  (struct  MD).  The  memoiy 
descriptor  defines  the  GEMDOS  TPA  limits  which  are  set  by  a call  to 
the  GEM  BIOS  function  Getnq>b( ).  Once  GEMDOS  has  been  Initiated, 
the  structure  values  may  not  be  changed.  See  Getmpbf ) for  details  on 
the  memoiy  descriptor  structure. 

savptr  long  Qx4A2 

A pointer  to  an  area  In  memoiy  used  to  save  the  CPU  roisters  dur- 
ing BIOS  function  calls. 

-nllops  WORD  Qx4A6 

The  number  of  floppy  disks  ph3rslcally  attached  to  the  ^tem  (0. 1, 
or  2). 


sav-contest  long  0x4AE 

Address  of  a memoiy  location  used  to  save  the  processor  context 
state  when  a catastrophic  error  occurs  (e.g..  an  odd  address  trs^  or 
divide  by  zero). 


-bnfl  2 lon^  0x4B4 

Two  buffer  control  block  (BCB)  pointers.  The  first  BCB  contains 
Information  about  the  data  sectors  on  the  disk.  The  second  BCB 
defines  the  sectors  for  the  file  allocation  table  (PAT)  and  the  dlrectoiy. 
A BCB  has  the  foUowlng  format 


struct  BCB  { 
struct  BCB  ‘b-llnk; 
WORD  b_bufdrv; 

WORD  b_buflyp: 

WORD  b_bufrec; 

WORD  b-dlrly; 

DMD  *b_dm; 

char  •b_bufir; 


/•  next  BCB  */ 

/•  drive  or  — 1 */ 

/*  buffer  type  */ 

/•  record  ^ cached  here  */ 

/*  dirty  flag  */ 

/•  Drive  Media  Descriptor  */ 
/•  the  buffer  Itself  */ 


The  DMD  structure  Is  not  defined  In  the  GEM  documentation. 


hr.  200  long  0x4BC 

This  Is  the  number  of  ticks  from  the  200  Hz  timer.  This  value  Is 
divided  by  four  to  obtain  the  50  Hz  ^tem  timer. 

the-emr  tyte(4]  0x4BE 

The  default  environment  string  Initially  set  to  four  NULL  characters. 

-drvbits  long  Qx4C2 
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This  is  the  value  retvimed  by  the  Drvmap( ) GEM  BIOS  function. 

^dsKbufy  long  Qx4C6 

The  address  of  a 1,024-byte  disk  buffer. 

-prt.ciit  WORD  Qx4EE 

The  number  of  times  the  Alternate-Help  key  combination  has  been 
pressed.  This  value  is  Initial^  set  at  — 1.  A value  of  0 initiates  the 
screen  dmnp  routine  to  output  the  screen  displ^  to  the  printer.  A 
value  greater  than  0 causes  the  screen  dump  routine  to  abort  and 
resets  -pit-cnt  to  — 1. 

_^base  long  0x4F2 

The  address  of  the  base  of  TOS.  TOS  may  reside  in  ROM  or  RAM.  If 
-^base  is  greater  than  pltyatop,  TOS  is  in  ROM. 

_8hell-p  long  0x4F6 

The  address  of  data  used  by  a shell. 

end-os  long  0x4FA 

The  address  of  the  byte  Immediate^  following  the  last  by  used  by 
TOS.  This  is  the  start  of  the  TPA. 

exec-08  long  Qx4FE 

The  address  of  a shell  program.  The  shell  program  is  executed  by  the 
BIOS  once  ^tem  Initialization  has  completed.  This  address  normally 
points  to  the  AES. 


Alphabetical  Listing  of  Atari  ST  System  Variables 


-bootdev 

WORD 

0x446 

-bufl 

2 longs 

0x4B4 

-cmdload 

WORD 

0x482 

colorptr 

long 

0x45A 

conterm 

byte 

0x484 

defshiftmd 

byte 

0x44A 

-drvbits 

long 

0x4C2 

-dskbufp 

long 

0x4C6 

end_os 

long 

0x4FA 

etv_critlc 

long 

0x404 

etv_term 

long 

0x408 

etv_tlmer 

long 

0x400 

etv_xtra 

longs 

0x40C 

exec_os 

long 

0x4FE 

flock 

WORD 

0x43E 

-frdock 

long 

0x466 

512  Atari  ST 


-fverlfy 

WORD 

0x444 

hdv_boot 

long 

0x47A 

hdv-bpb 

long 

0x472 

hdv_lnit 

long 

0x46A 

hdv_mediach 

long 

0x47E 

hdv_rw 

long 

0x476 

_hz_200 

long 

0x4BC 

_membot 

long 

0x432 

memcntlr 

byte 

0x424 

_memtop 

long 

0x436 

memval2 

long 

0x43A 

memvalid 

WORD 

0x420 

-nflops 

WORD 

0x4A6 

nvbls 

WORD 

0x454 

palmode 

long 

0x448 

phystop 

long 

0x42E 

_prt_cnt 

WORD 

0x4EE 

resvalld 

long 

0x426 

resvector 

long 

0x42A 

sav_context 

long 

0x4AE 

savptr 

long 

0x4A2 

screenpt 

long 

0x45E 

seekrate 

WORD 

0x440 

-shelL-p 

long 

0x4F6 

sshiftmd 

WORD 

0x44C 

swv_vec 

long 

0x46E 

_^base 

long 

0x4F2 

the_env 

byte(4j 

0x4BE 

themd 

long 

0x4BE 

-timr-ms 

WORD 

0x442 

-v-base_ad 

long 

0x44E 

-vbclock 

long 

0x462 

-vblqueue 

long 

0x456 

vblsem 

WORD 

0x452 
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Predefined  Message 
E^vents 


Because  GEM  is  a multitasking  operating  environment  several  appli- 
cations are  executing  at  any  given  time.  Among  these  applications  are 
routines  contained  in  the  ^plication  Environment  Services  (AES) 
such  as  the  dispatcher  and  screen  manager.  In  a multitasking  situa- 
tion, a mechanism  must  be  provided  to  allow  for  interaction  between 
applications  eind  between  the  user  and  the  ^tem.  GEM  provides  this 
mechanism  through  messages. 

An  application  may  send  a message  to  any  other  application.  The 
receiving  application  is  issued  a message  event  to  indicate  that  a mes- 
sage has  arrived.  When  the  receiving  application  acknovdedges  the 
message  event,  a 16-byte  message  buffer  is  sent  to  the  receiving  pro- 
gram. The  message  buffer  consists  of  an  eight  WORD  array  and  has 
the  following  format: 


Element 

Use 

0 

Message  type 

1 

ED  number  of  sending  application 

2 

Message  length  in  excess  of  16  bytes 

3-7 

Data  dependent  upon  message  type 

If  a message  has  more  than  16  b3rtes,  the  number  of  b)^es  remaining 
to  be  read  is  the  value  in  element  2 of  the  message  buffer.  The  remain- 
ing bytes  must  be  read  with  a call  to  the  AE^  function  appl-ieadf ). 

The  AES  has  several  predefined  message  types.  Below  is  a list  of 
these  message  types  along  with  its  defined  constant  name,  a descrip- 
tion, and  the  usage  of  the  remaining  message  buffer  elements. 
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AES  Predefined  Messages 

Type  Constant 

10  MN_SELECTED 

This  message  Is  sent  when  a user  selects  an  active  menu  item. 
Element  3— the  object  index  of  the  menu  title  selected. 

Element  4 — the  object  index  of  the  menu  item  selected. 

20  WM_REDRAW 

This  message  indicates  that  some  portion  of  the  window's  work  area 
needs  to  be  redrawn 

Element  3 — hemdle  of  the  window  to  be  redrawn 
Element  4 — x coordinate  of  the  redraw  area 
Element  5 — coordinate  of  the  redraw  area 
Element  6 — width  of  the  redraw  area 
Element  7 — height  of  the  redraw  area 

21  WM_TOPPED 

This  message  tells  an  application  that  a window  is  to  be  moved  to 
the  top  and  made  active. 

Element  3 — the  handle  of  the  window 

22  WM_CLOSED 

This  message  is  sent  when  the  user  has  requested  the  window  to  be 
closed. 

Element  3 — the  handle  of  the  window  to  dose 

23  WM_FULLED 

When  the  user  clicks  the  mouse  Inside  a window's  full  box.  this 
message  is  sent  to  the  application  owning  the  window. 

Element  3— the  handle  of  the  window 

24  WM-ARROWED 

This  message  Informs  the  application  when  a user  has  clicked  the 
mouse  in  the  arrow  or  scroll  bar  areas  of  the  window. 

Element  3 — the  handle  of  the  window 
Element  4— the  control  area  used,  as  follows: 

0 = page  up 

1 = page  down 

2 = row  up 

3 = row  down 

4 = page  left 

5 = page  right 

6 = column  left 

7 = column  right 
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Page  actions  are  caused  by  interactions  with  the  scroll  bars.  Row  and 
column  actions  are  caused  by  the  arrows. 

25  WM_HSLID 

This  message  informs  the  application  of  a new  position  requested 
for  the  horizontal  slider. 

Element  3 — the  handle  of  the  window 
Element  4 — requested  slider  position  (0-1000) 

26  WM_VSLID 

This  message  Informs  the  application  of  a new  position  requested 
for  the  vertical  slider. 

Element  3 — the  handle  of  the  window 
Element  4 — requested  slider  position  (0-1000) 

27  WM-SIZED 

This  message  Indicates  that  the  user  has  requested  a new  window 
size.  The  coordinates  given  this  message  indude  the  border  control 
areas  for  the  window. 

Element  3 — the  handle  of  the  window 

Element  4 — the  x coordinate  of  the  window  (usualfy  the  current 
coordinate) 

Element  5 — the  y coordinate  of  the  window  (usually  the  current 
coordinate) 

Element  6 — the  requested  width 
Element  7 — the  requested  height 

28  WMJMOVED 

This  message  tells  the  application  that  the  user  has  requested  a new 
location  for  the  window.  The  coordinates  given  by  this  message  Indude 
the  border  control  aueaus  for  the  window. 

Element  3 — the  handle  of  the  window 

Element  4 — the  requested  x coordinate 

Element  5 — the  requested  y coordinate 

Element  6 — the  requested  width  (should  remailn  the  saune) 

Element  7 — the  requested  height  (should  remain  the  same) 

29  WM_NEWTOP 

This  message  Indicates  that  one  of  the  application’s  windows  has 
been  platced  on  top  and  is  the  new  active  window. 

Element  3 — the  hauidle  of  the  window 

30  AC_OPEN 

This  message  is  sent  to  a desk  accessory  when  the  user  has  sdected 
it  from  the  E)esk  menu. 

Element  3 — the  ID  as  returned  by  the  menn_jr^iater( ) call 
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31  AC-CLOSE 

This  message  Is  sent  to  a desk  accessory  in  anyone  of  the  following 
conditions: 

the  current  application  has  just  terminated 
the  screen  Is  about  to  be  cleared 

the  window  manager  structure  are  about  to  be  reinitialized 

The  desk  accessory  should  delete  any  window  it  owns  firom  the  AES. 
Element  3 — the  ID  as  returned  fay  the  menii-iegister( ) call 


APPENDIX  F 

GEM  BIOS  and 
DOS  Error  Codes 


All  error  numbers  are  negative  and  fall  into  two  categories.  Hie  num- 
bers ranging  from  — 1 to  —31  are  BIOS  errors,  and  numbers  ranging 
from  —32  to  — 127  are  DOS  errors. 

BIOS  E^ror  Codes 


Number 

Description 

0 

OK  (no  error) 

Error  (general) 

-2 

Drive  not  ready 

-3 

Unknown  command 

-4 

CRC  error 

-5 

Bad  request 

-6 

Seek  error 

-7 

Unknown  media 

-8 

Sector  not  found 

-9 

Out  of  paper 

-10 

Write  fault 

-11 

Read  fault 

-13 

Write  on  write-protected  media 

-14 

Media  change  detected 

-15 

Unknown  device 

-16 

Bad  sectors  on  format 

-17 

Insert  other  disk  (request) 

Error  — 17  is  actually  a request  from  the  BIOS  for  another  disk  to  be 
inserted  into  drive  A.  This  allows  GEMDOS  to  think  it  has  two  drives 
on  a single  drive  ^tem. 
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GffltfDOS  Error  Codes 


Number 

Description 

-32 

Invalid  function  number 

-33 

File  not  found 

-34 

Path  not  found 

-35 

Handle  pool  exhausted 

-36 

Access  denied 

-37 

Invalid  handle 

-39 

Insufficient  memory 

-40 

Invalid  memory  blo<^  address 

-46 

Invalid  drive  specification 

-47 

No  more  flies 

-64 

Range  error 

-65 

GEMDOS  internal  error 

-66 

Invalid  executable  file  format 

-67 

Memory  block  growth  failure 

APPENDIX  G 

Listing  for 
FileEXTE^C 


The  function  rc-lnteraect( ) Is  not  part  of  the  GEM  ^tem.  Therefore  It 
Is  not  documented  as  part  of  GEM.  However,  it  Is  used  in  the  example 
programs  for  both  the  Megamax  and  the  Atari  development  ^tem.  In 
case  your  C programming  ^tem  does  not  include  this  function  in  its 
libraries,  the  source  code  is  provided  below.  The  file  shown  is  the  file 
used  by  the  Megamax  ^tem.  For  a description  of  the  function’s 
usage,  see  Appendix  A or  Chapter  12. 


ttlnclude 

<obdaf8.h> 

tt include 

<gemdef8.h> 

ttlnclude 

<o8blnd,h> 

ttdePine 

UORD  Int 

UORO  min(a,  b) 

UORD  a. 

b; 

< 

return  ((a  < b)  ? a : b); 

> 

UORO  max (a,  b) 

UORO  a,  b; 

{ 

return  ((a  >b)  7a  : b); 

> 

UORD  rc^ntersect(pl,  p2) 
GRECT  »pl,  »p2; 

< 

UORD  tx,  ty,  tu,  th; 
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tbi  ss  min  (p2->g_x  + p2->g_u«  pl->g-^  + pl->g_u) 

th  = min  (p2->g_jy  + p2->g-h,  pl->g_y  + pl->g-h) 

tx  = max  (p2->g^,  pl->g^); 

ty  = max  (p2->g^,  pl->g-jy); 

p2->g-x  = tx; 

p2->g_y  = ty; 

p2->g_w  = tw  - tx; 

p2->g-h  = th  - ty; 

return  ((tw  > tx)  &&  (th  > ty)); 


Index 


A 

AES»  5»  9.  212-241 
boxes.  215 
aleit  box.  215 
dialog  box.  215 
error  box.  215 
components  of,  212-214 
desk  accessory  buffer,  213 
limited  multitasking  kernel  and 
dispatcher,  213 
menu/alert  buffer,  212-213 
shell.  213 

subroutine  libraries,  212,  217-218 
events,  217 

function  names,  naming  conventions, 
254-255 
global  arrays,  9 
menus,  214-215 
menu  bar.  214 
menu  items.  214 
menu  tides,  214-215 
program  MENUl,  257-265 
program  MENU2. 265-274 
program  MENU  RSC.  255-257 
message  pipe,  217 
object  structures,  220-231 
APPLBLK  structure,  229-230 
BFTBLK  structure,  228-229 
ICONBLK  structure.  227-228 
object  flags,  222-223 
object  state  definitions,  221 
object  types,  223-225 
PARMBLK  structure,  230-231 
stnicture/arrangement  of  tree, 
220-225 


TEDINFO  structure.  225-227 
object  trees,  218-220 
children  in,  218 
dialog  box  object  tree,  219 
radio  button.  220 
root  In,  218 

program  LISTER,  274-289 
windows,  215-217 
components  of,  215-217 
work  area,  217 
Alert  box,  215 
Alignment  of  text  75-76 
center  text  alignment  76 
horizontal  text  alignment  75-76 
vertical  text  alignment  75, 76 
AND  operator,  logic  operations,  18 
And  program-writing.  XBIOS.  6-7 
Angles,  72-73 

measurement  method.  72-73 
tenths  of  degrees,  72-73 
rotation  angle,  setting  for  text  output 
74 

Animation 

animating  columns.  1 1 1-1 12 

base  values.  112,  113 

freeing  memoiy  for  second  screen. 

113 

output  113-114 
program  BOUNCE,  165-182 
program  writing,  primary  objective. 
181 

refresh  cycle,  1 12 
size  of  squares,  106 
smoother  look  for,  1 12 
speed.  111 

with  two  bit  laaps,  1 12-1 13.  1 14 
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Animation 
vertical  boxes,  112 
vertical  interrupt  112 
See  also  Raster,  program  BOUNCE. 
APPLBLK  structure.  229-230 
>^plication  Environment  Services,  See 
AES. 

^plications  manager.  254 
Arc.  72. 73 

counterclockwise  drawing  of,  73 
elliptical  arc.  73 
Arrow  shape 

holding  total  number  of  points,  65 
line^nd  slides,  67-68 
line  s^es,  66-67 
location  of.  65 
marker  types,  68-69 
scaling  of  markers.  69 
size  of.  65 
width  of.  66. 67 
Assembly  language.  7.  9 
Attributes,  resetting  of.  70 

B 

Bios(  ).36 

BITBLK  structure,  228-229 
Bit  m^.  13.  14-18.  94-114 
allocating  bit  map,  103-104 
allocation  of  memory.  103-104 
long  type  cast  operator,  103-104 
setting  base  addresses.  104 
animation,  106-114 
animating  columns.  111-112 
base  values,  setting.  112, 113 
freeing  memory  for  second  screen. 
113 

output  nature  of.  113-114 
refresh  cyde,  112 
size  of  squares,  106 
smoother  look  for.  112 
speed,  illusion  of  motion.  Ill 
with  two  bit  maps,  112-113. 114 
vertical  boxes  drawing,  112 
vertical  interrupt  1 12 
character  pointers.  99 
half-page  boundary.  95. 104 
implementation  of.  94-95 
location  of.  13 
logical  base  address.  98 
m£^ping  bits,  equation  for.  97-98 
memory.  95-97 

allocation  of  l^^tes,  95. 103-104 
base  address.  96 
linear  storage.  96 
mapping  process.  95-96 
refresh  rate,  97 
rows  on  video  display.  96 
words  as  access  ta  95 
physical  base  address.  98 


quick  method  of  creating  gr^hics,  13 
raster  as,  139-140 
representation.  20 
second  bit  map,  104-106 
logical  screen  base  address,  setting, 
105-106 

physical  base  address  setting,  106 
replacing  old  bit  map.  105 
setting  screen.  104 
and  text  s^pearance.  15-18 
use  of.  15-18 
uses  for.  14-18 
Bit  values,  text  dfect  76 
BOX.  223,  224 
Box  art  program 
flow  for  program.  137-138 
primary  function.  131 
replace  mode.  138 
size  of  box.  131 
transparent  mode,  138 
writing  modes.  138 
BOXCHAR,  223,  224 
Boxes 

alert  box,  215 
dialog  box.  215 
error  box.  215 
BOXTEXT.  223.  224 
BUTTON.  224 
Button  events.  273 
Buttons,  on  input  devices,  25 
Bytes,  94 


C 

Cell  height  17 
Center  text  alignment  76 
C function  call  interface.  VDI.  8-9 
C function  calls,  GEM.  7 
Character  cell,  15, 16-18 
ceU  height  17 
variables  for.  16 
Character  pointers,  bit  map,  99 
Characters,  interchaiacter  spacing, 
73-74 

CHECKED  state.  221.  222 
Circles 
VDI.  72-73 
angle  values,  72-73 
arc,  72. 73 

counterclockwise  drawing. 

arcs/pies.  73 
ellipse.  72 
ellipticai  arc,  73 
elliptical  pie.  73 
radius  of.  72 
C language 
program-writing,  10 
compiler.  10 
editor,  10 
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linker,  10 

resource  construction  program,  10 
Clipping,  27-28 
Clipping  rectangle 
multiple  woitetatlons,  92 
use  of^  92 

Clipping  rectangles,  creating,  93 
Closing  a woikstatlon,  32-^ 

Coarse  tune  register,  188 
Color  graphics,  115-138 
box  art  program,  131-138 
flow  for  program,  137-138 
primary  function,  131 
replace  mode,  138 
size  of  box,  131 
transparent  mode,  138 
writing  modes,  138 
color.  Intensity  levels,  115 
color  limitation,  24 
color  palette,  24.  1 16-1 17 
bits  used,  1 17 
memory  needed.  1 17 
color  planes,  24 

color  versus  monochrome,  120-121 
control  of  colors.  23-24 
electron  guns  in,  23 
memory  requirement  24 
monochrome  bit  maps.  116 
planes,  118-120 
interleaving,  119 
program  COLOR  121-131 
base  address.  130 
changing  colors  of  palette.  128 
color  table,  checking  support  by 
VDL  127 

extended  inquiry.  127 
nu  Interior,  128 

hexadecimal  values,  use  of,  127 
initializing  intensity  levels.  128-129 
palette  entries,  setting,  127 
replacing  palette.  131 
rotating  palette  colors,  129-130 
VDI  color  indices,  130-131 
resolution  of  Image,  121 
varying  Intensity.  24 
Color  output  program  RASTER  164 
Combination  of  effects,  text  effect  76-77 
Compiler,  94-95 
C programming.  10 
Computer  gr£q>hlcs,  1 1-28 
bit  map,  13, 14-18 
location  of,  13 

quick  method  of  creating  graphics, 
13 

representation,  20 
and  text  appearance,  15-18 
uses  for,  14-18 
color  graphics.  23-24 
color  limitation,  24 
color  palette,  24 


color  planes,  24 
control  of  colors,  23-24 
electron  guns  in,  23 
memory  requirement.  24 
varying  Intensity.  24 
device  coordinates.  2-23 
Cartesian  coordinate  intern,  22 
and  drawing  plane,  22 
most  commordy  used.  22-23 
and  resolution  of  output  device,  23 
display,  technology  of,  12-13 
graphics  routines.  13-14 
Line  A Handler,  13-14 
ideal  graphics  device,  26-27 
normalized  device  coordinate  (NDC), 
26-27 

raster  coordinates  (RC),  26 
workstation.  27-28 
input  devices,  25-26 
buttons.  25 
kQ^board,  25 
mouse.  25 

logic  operations,  18-19 
AND  operator,  18 
NOT  operator,  19 
OR  operator,  18 
XOR  operator,  19 
output  devices,  21-22 
impact  printers,  22 
nonimpact  printers,  22 
plotters.  21.  22 
storage  tube  display.  21-22 
vector  display.  21 
pixel.  11-12 

pixels,  monochrome  monitors.  12 
writing  mode.  19-20 
repl^ment  19-20 
reverse  transparent  mode.  20 
XOR  mode,  20 

Contiguous  format  raster,  151 
Contour  fill.  72 
CROSSED  state,  221 

D 

DEFAULT  flag.  222 
Desk  accessories,  213-214 
Desk  accessory  buffer.  213 
AES,  213 

Device  coordinates 
Cartesian  coordinate  ^tem,  22 
and  drawing  plane,  22 
most  commonly  used,  22-23 
and  resolution  of  output  device,  23 
Device-dependent  value,  line  types.  66 
Device  drivers,  3.  4,  31 
Device-Independence.  GEM,  7 
Device-specific  format  raster,  151,  152 
Dialog  box,  215 

See  also  FORM  program,  242-254 
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DISABLED  state.  221.  222 
Dispatcher.  213 
Dosound  Hmction.  program 
SOUNDEMO.  208-210 
Dot-matrix  printer.  21.  22 

E 

EDITABLE  flag.  222 
Editor.  C programming,  10 
EfTects 
text 

bit  values,  76 

combination  of  effects.  76-77 
italicized.  76 
light  intensity.  76 
outlined.  76 
shadowed.  76 
thickened.  76 
undexlined.  76 
Ellipse.  72 
Elliptical  arc.  73 
Elliptical  pie,  73 
Envelope  generatioa  188-189 
coarse  tune  register,  188 
envelope  period  calculation.  188 
fine  tune  raster,  189 
Error  box,  215 
Event  manager,  254 
Events,  217 
EXITllag.222 
Expiosioa  208 

P 

Face  files,  4 

File  selector  manager,  254 
Filled  shapes 
contour  fill  72 
fill  hatches.  70-71 
filling  complex  shapes.  71 
fill  patterns.  70 
interior-fill  settings.  70 
rectangles,  69.  70 
round^fiUed  rectangles,  69-70 
Filling  shapes,  color  graphics,  fill 
interior,  128 
Fill  setUngs,  27 
Fine  tune  register.  189 
Font  15-16 
Fonts 
text  75 

setting  index.  75 
and  workstatioa  75 
Format  Memoiy  Form  Definition  Block, 
141 

Form  manager.  254 
FORM  program,  242-254 
displaying  dialog  box.  251-252.  253 
drawing  box.  252-253 
drawing  dialog  box,  253 


exit  object  resetting,  253-254 
initializing  dialog  1^  250 
loading  resource  file,  249 
processing,  249 
screen  coordinates,  252 
Function  control,  272 

G 

GEM,  1-6,  7-9,  29-52 
application  steps 

Implementing  input/output  device, 
30 

initializing  application,  29-30 
locating  input/output  devices.  30 
processing  program.  30 
releasing  input/output  device.  30 
terminate  program,  30 
and  assembly  language,  7, 9 
C function  calls,  7 
computers  used  with.  3 
device  drivers  and.  3. 4 
device-independence.  7 
interface.  3-4 
accessing.  7 
modules  of,  4-5 
AES.  5.9 
GEMDOS,  4 
VDl  4.  7-8 
workstation,  31-33 
dosing  a workstation,  32-33 
device  drivers,  31 
opening  several  workstations.  32 
opening  a workstation.  31 
physicd  workstation.  31 
virtual  workstation,  31, 32 
Gemdos  ( ),  37 
GEMDOS.  4 

GEM  outline  program.  33-^42 
application  function,  40 
s^plicatlon  overhead.  37-38 
declarations  for  variables.  37-38 
type  definition,  37 
application-specific  data,  38 
GEM  related  functions 
retrieving  screen  resolution,  39-40 
setting  global  variables.  39 
GEM-related  functions 
virtual  workstation  function.  38 
header  files,  33.  36-37 
defining  constant  values.  37 
defining  functions,  36-37 
input/output  control  36 
kinetic  line  art  42-52 
defining  boundaries.  49 
do-while  loop,  51 
flow  of  program,  49 
line-drawing  initialization.  49-51 
XOR  writing  mode,  48 
main  program,  40-42 
application-specific  routines,  41 
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clean-up/exit  41-42 
GEM  access  initialization.  40-41 
oiganizlng  outline*  33 
Glol^  arrays 
AES.  9 
VDI.8-9 

Graphics  Device  Operating  System 
(GDOS).  4-5 

Graphics  Environment  Manager.  See 
GEM. 

Graphics  libraiy  routines,  290-312 
box  outline,  moving.  291 
changing  mouse  form.  291-292 
dragging  outline,  291 
expanding  box  outline.  291 
expandln^contracting  rectangle.  292 
mouse  position,  restoring.  291 
program  Mouse.  293-312 
application-speciflc  data.  295-31 1 
changing  program.  31 1-312 
free  tree.  294, 306 
menu  bar,  293-294, 306 
mouse  events.  307-308 
redrawing  method.  309-310 
size  of  objects,  309 
slide  bars,  equation  used,  310 
updating  screen.  308-309 
returning  handle,  291 
shrinking  box  outline,  292 
sliding  b^  293 
watching  rectangle.  293 
Graphics  manager.  254 
Graphics  routines,  13-14 
Une  A Handler.  13-14 
Graphic  text,  versus  regular  text,  73 
Gravity,  calculation  for,  program 
BOUNCE.  180 
Gunshot  207-208 


H 

Hatches,  fill  hatches,  70-71 
Header  flies 

defining  constant  values,  37 
defining  functions,  36-37 
lnput/ou4>ut  control,  36 
Height 

measurement  in  points.  73 
of  text  74-75 
pixel  sizes,  74-75 
point  size.  74-75 
Hexadecimal  notation,  use  of.  line 
styles.  78 

HIDETREE  flag.  222-223 
High,  Memory  Form  Definition  Block, 
141 

Horizontal  lines,  word-aligned.  84 
Horizontal  text  alignment  75-76 


I 

IBOX,  223,  224 
ICONBLK  structure.  227-228 
Ideal  graphics  device 
non^ized  device  coordinate  (NDC). 
26-27 

raster  coordinates  (RC).  26 
workstation.  27-28 
Impact  printers,  22 
Implementing  input/output  device. 
GEM,  30 

INDIRECT  flag.  223 
Initializing  application.  GEM,  29-30 
Input  devices 
buttons.  25 
kQrboard.  25 
mouse.  25 

Input/output  control,  sound.  190 
Intercharacter  spacing.  73-74 
Interface.  GEM.  accessing.  7 
Interior-fill  settings,  70 
Interleaved  format  raster.  151 
Italicized,  text  effect  76 

J 

Justified  text  73-74 

K 

Keyboard.  25 

Key  dick,  setting,  program  SOUNDEMO. 

203.204 
Kinetic  line  art 
defining  boundaries.  49 
do-whlle  loop,  61 
flow  of  program.  49 
line-drawing  inltializatioa  40-51 
XOR  writing  mode.  48 

L 

Laser  printers.  22 
Laser  sound.  208 
LASTOB  flag.  222 

Libraries,  AES.  212.  217-218.  254-255 
Light  intensity,  text  effect  76 
Limited  multitasking  kemd  and 
dispatcher.  AES.  213 
Line  A H^dler,  13-14 
Line  A handler,  2, 6 
Line  drawing 
arrow  shape,  65-69 
holding  total  number  of  points,  65 
line-end  stjies.  67-68 
line  stydes,  66-67 
location  of,  65 
marker  types.  68-69 
scaling  of  markers.  69 
size  ot  65 
width  of.  66,  67 
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Line^nd  styles,  67-68 
types  of,  68 
Line  settings,  27 
Line  styles 
types  of,  67 
VDI 

changing  program  for,  86 
function  for  drawing  lines,  78, 84 
hexadecimal  notation,  use  of,  78 
setting  index,  78 
user-defined  line  stjde.  78 
user-defined  fill  pattern,  78 
variable  style,  78 
word-aligned  horizontal  lines,  84 
Linker,  C programming,  10 
LISTER  program,  274-289 
Locating  input/output  devices.  GEM,  30 
Logical  base  address 
bit  map,  98 

second  bit  map,  105-106 
Logic  operations 
AND  operator,  18 
NOT  operator,  19 
OR  operator,  18 
XOR  operator,  19 
Long  tyi^  cast  operator,  bit  map, 
103-104 


M 

Marker  types,  68-69 
device-dependence,  69 
scaling  of  markers,  69 
types  of,  69 

Mask  raster,  use  of.  168, 180 
Memory 
bit  m£q) 

allocation  of  bytes.  95,  103-104 
base  address,  96 
linear  storage.  96 
moping  process.  95-96 
refresh  rate,  97 
rows  on  video  display.  96 
words  as  access  to,  95 
components  of,  94 
Memory  Form  Definition  Block 
format  141 
high,  141 
planes,  141 
wide,  141 

Menu/alert  buffer,  212-213 
AES.  212-213 
Menu  manager,  254 
Menus 

menu  bar,  214 
menu  items,  214 
menu  titles.  214-215 
Message  pipe,  217 


Messages 

menu-selected  message,  258, 264 
receiving,  257-258 
MFDBs 

program  BOUNCE,  167 
program  RASTER,  157 
Microprocessor,  supervisor  mode, 
203-204 

Monochrome  monitor,  versus  color, 
120-121 

Monochrome  monitors,  pixels,  12 
Monochrome  output  program  RASTER 
163-164 
Motion 

Illusion  of.  Ill 
program  BOUNCE.  165-182 
See  also  Animation. 

Mouse,  25 

hot  spot  of,  291-292 
See  also  GrE4)hlcs  Ubraiy  routines. 
Mouse  events,  273 
program  Mouse,  307-308 
Multiple  workstations 
VDI 

application-specific  routines,  92 
clipping  rectangle,  92. 93 
closing  workstations,  93 
MULWORK,  87-93 
setting  attributes  of  each.  92-93 
transparent  writing  mode,  92^93 
vlrtu^  workstations,  opening,  92 
Multitasking,  limited  multitasking 
kernel  and  dispatcher.  213 

N 

Noise  enable  bit,  sound,  190 
Noise  period.  188 
NONE  flag.  222 
Nonimpact  printers,  22 
Normalized  device  coordinate  (NDC). 
26-27 

Normalized  device  coordinates,  y-axis 
unit  69 

NORMAL  state,  221,  222 

NOT  operator,  logic  operations,  19 

O 

Object  manager.  254 
Object  structures 
APPLBLK  structure,  229-230 
BITBLK  structure,  228-229 
ICONBLK  structure,  227-228 
object  flags,  222-223 
object  state  definitions,  221 
object  types,  223-225 
PARMBLK  structure,  230-231 
structure/arrangement  of  tree, 
220-225 

TEDINPO  structure.  225-227 
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Object  trees 
^ildren  in,  218 
dialog  box  object  tree.  219 
radio  button,  220 
root  in,  218 

Opaque  copy  raster  function,  158-155, 
161.  162 
copy  modes,  154 
function  call  from  C,  153 
logic  operations,  154 
parameters  of.  154 
pixel  pixel  copying,  155 
rectangular  area,  154-155 
writing  mode,  154 
Opcode,VDI,8,9 
Opening  several  woiicstations,  32 
Opening  a workstation.  31 
Curating  ^tem,  TOS,  1-2 
OR  operator,  logic  operations.  18 
Outline  attribute,  70 
Outlined,  text  effect  76 
OUTLINED  state,  221 
Output  devices 
impact  printers.  22 
and  line  stjfies,  66-67 
nonimpact  printers,  22 
plotters,  21, 22 
storage  tube  display.  21-22 
vector  display,  21 
Output  functions,  *V.”  74 

P 

Page,  94 

Palette,  See  Color  graphics. 

PARMBLK  structure,  230-231 
Patterns 
VDI 

changing  program  for.  86 
checkerboard  pattern,  85 
components  of,  85 
planes  in,  85-86 
user-defined  fill  pattern,  86 
word-aligned,  86 
Pen  plotters,  21. 22 
Period,  determining,  186 
Physical  base  address 
bit  map.  98 
second  bit  map.  106 
Physical  workstatioa  31 
Pies.  72-73 

counterclockwise  drawing,  73 
elliptical  pie.  73 
Pixel  11-12 

Pixel  by  pixel  copying,  opaque  copy 
raster  function,  155 

Pixels 

erasing  from  screen.  21 
mapping  bits,  97-98 
equation  for,  97-98 


monochrome  monitors,  12 
Pixel  sizes,  text  74-75 
Planes 

color  gnq)hics,  interleaving,  119 
Memory  Form  Definition  Block,  141 
and  patterns,  85-86 
storing,  raster  formats,  141, 151 
Plotters.  21. 22 

Points,  height  measurement  73 
Point  size,  text  74-75 
Printers 

impact  printers.  22 
nonimpact  printers.  22 
Processl^  program.  GEM.  30 
Programrri^le  Sound  Generator  (PSG). 
185, 191 

Program-writing,  C language,  10 
Protected  memory  access,  program 
SOUNDEMO,  203-204 
PSG,  program  SOUNDEMO,  206 
PSG  access,  program  SOUNDEMO. 
205-206 

9 

Query  fimctions,  *VQ,‘*  74 

R 

Race  car  sound,  208 
Radius,  of  circle.  72 
Raster 

Memory  Form  Definition  Block,  141 
format  141 
high,  141 
planes,  141 
wide,  141 

opaque  copy  raster  function,  153-155 
copy  modes,  variely  of,  154 
function  call  from  C,  153 
logic  operations,  154 
parameters  of,  154 
pixel  by  pixel  copying,  155 
rectangular  area,  specifying 
coordinates.  154-155 
writing  mode,  154 
program  BOUNCE.  165-182 
animation  technique.  167,  181 
application  specific  functions. 
179-181 

bit  maps  used,  166 
drawlrig  of  ball.  180 
erasing  ball.  180, 181-182 
gravify,  calculation  for.  180 
mask  raster  use  of.  168,  180 
MFDBs,  defined,  167 
operation  of.  168, 179-182 
position  of  ball  180-181 
program  RASTER  156-165 
application  routines,  158-159 
changing  program,  165 
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Raster 

color  output  164 
holding  raster  images,  157 
MFDBs,  defined,  157 
monochrome  output  163-164 
replace  mode,  162 
screen,  setting  up,  161 
setting  up  rasters,  160-161 
temporary  raster  area,  161-162 
transformation  function,  159-160 
writing  mode,  162 
raster  conversion,  156 
raster  formats,  141,  151-153 
color  in,  153 
contiguous  format  151 
device-specific  format  151.  152 
Interleaved  format  151 
standard  format  151, 152 
storing  planes,  141, 151 
requirements  for  use.  140-141 
transparent  copy  raster  function, 
155-156 

color  Index  array,  156 
function  call  from  C,  153 
parameters  of,  155 
replace  mode.  156 
writing  mode,  156 
XOR  mode,  156 
use  in  programs,  153 
Raster  coordinates,  y-axis  unit  69 
Raster  coordinates,  (RC).  26 
RBUTTON  flag,  222 
Rectangles 
VDI,  69-72 

attributes,  resetting  of,  70 
contour  fill,  72 
filled  rectangles,  69.  70 
fill  hatches,  70-71 
filling  complex  shapes,  71 
fill  patterns,  70 
interior-fill  settings,  70 
outline  attribute,  70 
rounded/filled  rectangles,  69-70 
rounded  rectangles,  69 
Refresh  cycle,  animation.  112 
Refresh  rate,  bit  map.  97 
Releasing  Input/output  device,  GEM.  30 
Replacement  writing  mode.  19-20 
Replace  mode 
box  art  program.  138 
program  RASTER,  162 
transparent  copy  raster  function,  156 
Resolution  of  image,  color  graphics.  121 
Resource  construction 
program,  C 
programming,  10 
Resource  manager,  254-255 
Reverse  transparent  mode,  writing 
mode,  20 


Rotating  text  and  workstation 
capability,  74 

Rotation  angle,  setting  for  text  output 
74 

Rotation  of  color  palette.  129-130 
Rotation  text  and  workstation 
capabillQr.  74 

Rounded/filled  rectangles,  69-70 
Rounded  rectangles,  69 

S 

Scaling  of  markers,  69 
ScrEq}  manager,  255 
Screen  manager,  213 
SELECTABLE  flag.  222 
SELECTED  state,  221,  222 
Set  funcUons,  '‘VS.**  74 
Shadowed,  text  effect  76 
SHADOWED  state,  221-222 
Shell.  213 
AES.  213 

Size,  line  size,  arrow  shape,  65 
Sound,  183-211 
envelope  generation,  188-189 
coarse  tune  register,  188 
envelope  period  calculation,  188 
fine  tune  register,  189 
generation  of  (physical  view),  183-184 
frequency,  184 
waveform,  183-184 
noise  period,  188 
output  190-191 
activation  of  speaker,  190 
input/output  control  190 
noise  enable  bit  190 
tone  enable  bit  190 
Programmable  Sound  Generator 
(PSG),  185, 191 

program  SOUNDEMO,  191-211 
changing  program,  211 
clearing  sound  registers,  206-207 
defined  constants,  205 
Dosound  function,  208-210 
explosion,  208 
gunshot  207-208 
key  dick,  setting,  203.  204 
laser  sound,  208 
mix  of  sounds,  205 
protected  memory  access,  203-204 
PSG,  use  of.  206 
PSG  access,  205-206 
race  car  sound,  208 
sound  chip,  access  to,  205 
sound-demo  array,  209, 210 
sound  effect  functions,  207-208 
whistle,  208 
voice  period  registers 
parts  of.  190 
period,  determining,  186 
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setting  of,  185-188 
tone  period,  determining.  186-187 
volume  control,  190 
Speed,  illusion  of  motion.  111 
Standard  format,  raster,  151, 152 
Storage  tube  display.  21-22 
STRING.  224 

Subroutine  libraries,  212,  217-218, 
254-255 

AES.  212,  217-218.  254-255 
Supervisor  mode,  microprocessor, 
203-204 


T 

TEDINPO  structure,  225-227 
Terminate  program,  GEM,  30 
TEXT.  223,  224 
Text 

VDI,  73-77 

alignment  of  text  75-76 
font  variations,  75 
graphics  text  73 
height  settings,  74-75 
interchaiacter  spacing,  73-74 
Justified  text  73-74 
justufied  text  73-74 
setting  rotation  angle,  74 
text  attributes,  74 
text  effects,  76-77 
writing  initial  string.  73 
Text  appearance 
bit  map,  use  of,  15-18 
cell  height  17 
font  15-16 
typeface,  15-16 
tj^size,  15-16 
Text  settings,  27 
Thickened,  text  effect  76 
TITLE,  224 
TOCHEXT  flag,  222 
Tone  enable  bit  sotind,  190 
Tone  period,  determining,  186-187 
TOS  1-2  " 

GEM,  1-6,  7-9,  29-52 
Line  A handler,  2, 6 
XBIOS,  1, 6 

Transparent  copy  raster  function, 
155-156 

color  index  array.  156 
fimctlon  call  from  C.  153 
parameters  of,  155 
replace  mode,  156 
writing  mode,  156 
XOR  mode,  156 

Transparent  mode,  box  art  program, 
138 

Transparent  writing  mode,  writing 
mode.  93 


Typeface,  15-16 
Typesize,  15-16 

U 

Underlined,  text  effect  76 

V 

*V,”  output  functions.  74 
VDI.  4 

application  functions,  53-77 
changes  to  program,  77-78 
circles.  72-73 
line  drawing,  65-69 
rectangles,  69-72 
text  settings,  73-77 
C function  call  interface,  8-9 
face  flies,  4 
global  arrays,  8-9 
Graphics  Device  Operating  System 
(GDOS),  4-5 
line  stjdes,  78-85 
variable  style.  78 
multiple  workstations,  86-93 
application-specific  routines,  92 
clipping  rectangles,  92.  93 
closing  workstations,  93 
MULWORK,  87-93 
setting  attributes  of  each.  92-93 
transparent  writing  mode.  92-93 
virtual  workstations,  opening,  92 
opcode,  use  of.  8,  9 
opening  a workstation.  53 
patterns,  85-86 
planes  in,  85-86 
word-aligned.  86 
plotting,  technique  for,  8 
raster.  139-182 
explanation  of,  139-140 
Memory  Form  Definition  Block,  141 
opaque  copy  raster  function. 

153-155,  161,  162 
program  BOUNCE,  165-182 
program  RASTER,  156-165 
raster  conversion,  156 
raster  formats,  141,  151-153 
transparent  copy  raster  function, 
155-156 

Vector  display,  21 
Vertical  interrupt  animation,  1 12 
Vertical  text  alignment  75,  76 
Virtual  Device  Interface,  See  VDI. 
Virtual  workstation,  31,  32 
Virtual  workstations,  opening,  multiple 
workstations.  92 
Voice  period  registers 
parts  of,  190 
period.  186 
setting  of.  185-188 
tone  period,  186-187 
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Volume  control,  sound,  190 
‘VQ.”  query  functions,  74 
‘VS/*  set  factions,  74 


W 

WhlsUe,  208 

Wide,  Memory  Form  Definition  Block, 
141 

Width,  line  width,  arrow  shape,  66, 67 

Vnndow  manager,  255 

Wndows,  313-375 
components  of,  215-217,  313-314 
messes,  317-318 
procedures  used,  315-316 
programs,  event  driven.  315-316 
program  WINDOWl,  321-346 
program  WINDOWl,  closing  a 
window,  341, 344, 345 
program  WINDOWl,  creating  window, 
340 

program  WINDOWl 
deleting  a window,  341-342 
handle  of  window.  342, 345 
program  WINDOWl 
initialization  process,  339 
message  event,  344 
opening  four  windows,  321 
opening  a window,  341, 344 
organization  changes  made  to,  338 
program  flow,  343-344 
program  WINDOWl,  redrawing  of 
window.  342-343 
program  WII^OWl,  resource  file, 
?????? 

program  WINDOWl 
turning  mouse  off.  341 
using  program.  346-347 
program  WINDOW2.  347 
creating  window.  372 
drawing  text  371-372 
redrawing  of  window,  372-374 
resource  file,  347-348 
scroll  bar,  ratio  for,  369-370 
slider,  size/position,  368-369 
WM  ARROWED  message,  373-374 
redrawing  a window.  318-320 
topmost/active  window,  315 
window  handler,  314-315 


window  manager  routines,  316-317 
changes  to,  316 
opening  window.  316 
removing  window,  316 
returning  handle  to,  316 
updating  window,  316-317 
WINDOW  structure.  320-321 
work  area,  217 

Word-aligned  horizontal  lines,  84 
Words.  94 
Workstation,  27-28 
clipping,  27-28 
fill  settings,  27 
GEM 

closing  a workstation,  32-33 
device  drivers,  31 
opening  several  workstations,  32 
opening  a workstation,  31 
physical  workstation,  31 
virtual  workstation,  31,  32 
graphics  attributes,  27 
line  settings,  27 

opening  a workstation,  information 
supplied  ty.  86-87 
text  settings,  27 
writing  modes,  27 
Writing  mode 
program  RASTER,  162 
replacement  19-20 
reverse  transparent  mode,  20 
txansparent  copy  raster  function,  156 
transparent  writing  mode,  93 
XOR  mode,  20 
Writing  modes,  27 
box  art  program.  138 
header  fUes,  37 

X 

XBIOS.  1.  6 
Xbios  ( ).  37 

XBIOS.  and  program  writing,  6-7 
XOR  mode 

transparent  copy  raster  function,  156 
writing  mode,  20 

XOR  operator,  logic  operations.  19 

Y 

Y-axis  unit 

normalized  device  coordinates,  69 
raster  coordinates,  69 
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Atari  ST  Applicatibn  Programming  is:  - — 

the  combination  of  Atari  ST  and  Digital  Research’s  Graphics  Environment  [ 

Manager  (GEM)  which  provides  everyone  with  a personal  computer  that  is  easy  [ 

and  intuitive  to  use.  Now  you  can  learn  to  write  complete  software  programs  j 
for  this  dynamic  duo  of  the  computer  world.  With  Atari  ST  Application 
Programming  you  will  learn  and  understand  the  varied  concepts  associated 
with  a graphics  based  user  interface. 

Not  just  a reference  guide,  this  book  takes  you  deep  into  the  minds  of  the 
software  engineers  who  built  this  system.  You  will  see  the  basic  building  blocks 
from  the  Virtual  Device  Interface  to  the  Application  Environment  Services  to  ^ 
the  multi-voiced  sound  effects.  The  book  presents  detailed  sample  programs  ; 
that  you  can  experiment  with  and  learn  from. 

With  Atari  ST  Application  Programming,  you  can: 

■ See  how  to  create  complex  graphic  images. 

□ Work  with  windows  and  menus  to  make  your  program  easier  to  use.  ^ 

■ Find  out  how  to  create  lavish  sound  effects. 

■ Use  the  mouse  to  select,  move,  and  size  objects. 

■ Create  resource  files  for  elegant  screen  designs. 

■ Write  a program  that  shows  you  the  secrets  of  animation.  , 

0 

■ Have  an  instant  library  of  over  a dozen  fun  and  useful  programs. 

In  clear,  concise,  and  understandable  language,  this  book  gets  your  imagination 
working  in  high  gear.  Once  you  have  finished  reading  this  book,  you’ll  be  ready  to  f 

write  sophisticated  and  robust  applications  that  rival  even  the  commercial  packages.  f 

started  with  the  very  basics  that  a programmer  must  know  in  order  to  program  this 
computer.  On  top  of  this,  we  built  a set  of  tools  that  can  help  programmers  reach  beyond  c 

the  limit  of  their  abilities.”  — Lawrence  j.  pollack  and  eric  j.t  weber  c 


Lawrence  J.  Pollack,  author  of  two  other  books:  Programming  in  C on  the  IBM 
PC  and  Programming  the  Macintosh  tn  C;  a computerized  medical  management 
package;  and  a database  management  system.  Eric  J.T.  Weber  is  an  independent 
computer  consultant  who  has  written  numerous  programs  and  users 
documentation. 
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